# 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 Rush](https://cloud.getrush.ai/run/add-search-autocomplete/wagtail/). Opens 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`

```json
{
  "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.

## 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

- [Add Security Headers to a Wagtail Site from a Linear Issue](https://getrush.ai/run/add-security-headers/wagtail/)
- [Add Schema.org Structured Data to a Wagtail Site](https://getrush.ai/run/add-structured-data/wagtail/)
- [Add Type Hints to a Wagtail Codebase](https://getrush.ai/run/add-type-hints/wagtail/)

## More jobs like this: Hand off a long task

- [Add Search to a Hugo Site](https://getrush.ai/run/add-search/hugo/)
- [Add Search to a Jekyll Site](https://getrush.ai/run/add-search/jekyll/)
- [Add Search to a Pelican Blog](https://getrush.ai/run/add-search/pelican/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
