All jobs

Add Search Autocomplete to a Wagtail Site

Yes. An agent adds autocomplete fields to the page models, a JSON suggestions view on the search backend and a header listbox, with tests, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads how search works on the site before adding a suggestions endpoint. In a site shaped like wagtail/bakerydemo, requirements/base.txt pins Django>=6.0,<6.1 and wagtail>=8.0,<8.1, settings/base.py sets WAGTAILSEARCH_BACKENDS to the wagtail.search.backends.database backend with index bakerydemo, and requirements/production.txt swaps in Elasticsearch. urls.py routes search/ to bakerydemo.search.views.search, which, on the database backend, runs .live().search(query) on BlogPage, BreadPage, LocationPage and RecipePage separately, records a hit on wagtail.contrib.search_promotions Query, and paginates ten results into search/search_results.html. includes/header.html has two forms with action="/search", inputs named q with autocomplete="off" and ids search-input and mobile-search-input. blog/models.py indexes introduction, subtitle and body with index.SearchField, the other three page models index their own fields the same way, and base/models.py already uses index.AutocompleteField on the Person model's first and last names, so the pattern is in the repository.

It adds index.AutocompleteField("introduction") and index.AutocompleteField("subtitle") to BlogPage.search_fields, introduction to BreadPage, backstory to RecipePage and address to LocationPage, matching each model's existing SearchField list, and runs ./manage.py update_index so the database backend indexes them. Then it adds autocomplete(request) to search/views.py: it reads q, returns an empty list for fewer than two characters, runs Page.objects.live().autocomplete(q) on the configured backend, takes the first few results, and answers JsonResponse with each page's title, its url, and the content type label the results template already derives from content_type.model. urls.py gets search/autocomplete/ as search_autocomplete, placed before the search/ pattern.

The client side is a small addition to static/js/main.js, which is 71 lines today. It attaches to both header inputs, debounces keystrokes, fetches the endpoint, and renders a ul with role="listbox" under the field, marking the input role="combobox", aria-autocomplete="list" and aria-expanded, with arrow keys moving aria-activedescendant and Enter following the chosen link. Submitting the form still goes to /search unchanged, so the page works with JavaScript off. The new markup uses the existing listing-card naming for its classes so the style file needs only a few lines.

Tests go in a new bakerydemo/search/tests.py in the style of base/tests/test_seo.py: a WagtailPageTestCase that creates a BlogPage under the root, calls update_index, requests /search/autocomplete/?q= with a prefix of its title, asserts the JSON contains the page, and asserts a one-character query answers an empty list. Before pushing it runs what .github/workflows/ci.yml and the Makefile run: make lint-server for ruff format --check, ruff check and curlylint, make lint-client for the ESLint and Stylelint configs, ./manage.py check, ./manage.py makemigrations --check --noinput, which passes because search fields need no migration, and ./manage.py test. It then starts the server with the demo fixtures, types in the header box, and captures the suggestions for the pull request.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add search autocomplete to this Wagtail site and open a pull request. Read requirements/base.txt, bakerydemo/settings/base.py, bakerydemo/urls.py, bakerydemo/search/views.py, bakerydemo/templates/search/search_results.html, bakerydemo/templates/includes/header.html, bakerydemo/static/js/main.js, the search_fields in blog, breads, recipes, locations and base models, bakerydemo/base/tests/test_seo.py, Makefile and .github/workflows/ci.yml first. Add index.AutocompleteField entries for the text fields each page model already indexes with SearchField. Add an autocomplete view in search/views.py that reads q, returns an empty list under two characters, runs Page.objects.live().autocomplete(q) on the configured backend, and answers JSON with title, url and the content type label the results template uses; route it at search/autocomplete/ before search/. In static/js/main.js attach to both header inputs with debounce, render a listbox with combobox ARIA attributes and keyboard navigation, and leave form submission to /search as it is. Add bakerydemo/search/tests.py as a WagtailPageTestCase covering a title prefix match after update_index and the short-query empty answer. Run make lint-server, make lint-client, ./manage.py check, ./manage.py makemigrations --check --noinput and ./manage.py test, then run the server with the demo data and include a screenshot of suggestions in the pull request. Do not change the results page or the search view's ranking.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request that adds bakerydemo/search/tests.py, adds a view and a URL pattern, extends search_fields in four model files, appends to static/js/main.js and the site's stylesheet, and marks up the two header inputs. The description shows the manage.py test result with the new tests, the two lint targets passing, and a screenshot of the header with suggestions open for a typed prefix.

On a repository with this CI workflow, the pull request runs the server lint job with uv, the client lint job with npm ci, and the test job with check, makemigrations --check and test. Nothing in the change adds a migration or a dependency, so all three jobs run on the pull request as they do on main.

A reviewer checks that the endpoint only returns live pages and never a draft title, that the suggestion count and the two-character minimum suit the site's traffic, since every keystroke past the debounce is a query, and that the listbox is reachable by keyboard and screen reader. Then they decide whether to switch production's Elasticsearch index, which the pull request does not touch, to a prefix analyser for better matches.

Run it on every new Wagtail site

Send one POST /o/{org}/sessions per Wagtail repository with this prompt and that repository in resources. Each run reads its own search backend and page models, so a site on Elasticsearch gets the same view with its autocomplete fields built into that index, and a site with a django-filter search page gets the suggestions wired to that form instead of a header input.

Give the API key a webhook_url and Rush POSTs run.completed when each turn finishes, with the session_url to read the pull request link from, so a handler on your server can post it where that site's editors and developers review.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Autocomplete fails quietly: the index does not include the new fields until update_index runs, a listbox that looks fine with a mouse is unreachable from a keyboard, and the database backend behaves differently from Elasticsearch. The agent runs the site with its demo data in a sandbox with a browser, types into the header, and keeps the screenshot and the test output in the run's record, so the pull request shows suggestions appearing rather than code that should show them.

The repository's own checks, two lint targets and the Django test run with a migration check, take long enough that people skip the client lint. The agent runs all of them before pushing, so the pull request opens green, and the same request body works for every Wagtail site a team maintains.

Frequently asked questions

Does this work on the database search backend?

Yes. The repository's default backend is wagtail.search.backends.database, and autocomplete() runs on it once the models declare AutocompleteField entries and update_index has run. Production's Elasticsearch backend supports the same call with its own prefix matching.

Why not reuse the existing search view?

That view renders a full page, records a Query hit for the search promotions feature and paginates ten results. Suggestions need a small JSON answer per keystroke and should not count as searches, so they get their own view and URL, and the results page stays as it is.

Is the suggestion list accessible?

The input becomes a combobox with aria-autocomplete="list" and aria-expanded, the list is a listbox of option elements, arrow keys move aria-activedescendant, Escape closes it, and Enter follows the active link. With JavaScript off the form submits to /search exactly as before.

Will drafts or unpublished pages appear?

No. The view queries Page.objects.live(), so only published pages are candidates, and the test creates a page and asserts it appears only after it is live and indexed.

More Wagtail jobs

More jobs like this: Hand off a long task

Keep reading