You can add live search suggestions to a WordPress site by querying its REST API from JavaScript as a visitor types. Start with the built-in /wp/v2/search route; create a custom REST endpoint only if you need search behavior or result fields that route cannot provide. The key work is not just fetching results: the widget should remain usable with a keyboard, handle failures and empty queries, and show only content visitors are allowed to see.
Choose the built-in search route or a custom endpoint
WordPress’s REST API lets a theme or plugin request site content as JSON for interactive front-end features. Its handbook describes the API as a more structured and predictable option for theme and plugin use than admin-ajax. See the WordPress REST API handbook.
| Approach | Best fit | Trade-off |
|---|---|---|
Built-in /wp/v2/search |
A straightforward public suggestion list using the site’s standard search results. | Less control over filters, content types and returned fields. |
| Custom REST endpoint | Search needs custom filters, custom content types, different query behavior or tailored result fields. | More code to build, secure and maintain. |
The REST API reference documents /wp/v2/search, along with content routes such as /wp/v2/posts and /wp/v2/pages. Do not assume a parameter or response field without checking the target site’s API schema: available details can depend on its WordPress version and configuration. Consult the REST API reference and the site’s API index.
Build a small autocomplete with the built-in route
1. Add a search form and suggestion area
Keep a normal search form so visitors can submit a complete query and reach a full results page even if JavaScript is unavailable or they prefer not to select a suggestion. Give the input a visible label. Place a suggestion list nearby, initially hidden, and expose clear loading, no-results and error states as appropriate.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minute2. Enqueue a front-end script
Load a small JavaScript file through your theme or plugin rather than embedding it in page content. Make the site’s REST API base URL available to that script using the appropriate WordPress enqueue/localization approach for your implementation. Avoid hard-coding a domain-specific API URL if the site may move or run in a different environment.
3. Request suggestions as the query changes
When the input changes, wait briefly before sending a GET request to the site’s /wp/v2/search route. Add the query using the parameters supported by that site’s schema, then parse the JSON response and render a limited number of useful suggestions. The API reference documents the route, but the precise parameters and response shape should be verified on the site where the feature will run.
Rank #2
4. Keep results aligned with the latest input
Autocomplete requests can finish out of order: a response for an earlier, shorter query might arrive after the response for the text currently in the box. Prevent that older response from replacing newer results—for example, cancel the previous request when possible or compare each response with a request identifier before rendering it. Also avoid sending a request for an empty or whitespace-only query.
5. Make suggestions actionable
Each suggestion should link to its result. Support keyboard movement through suggestions, selection, and dismissal, and keep focus behavior understandable. Communicate loading, no matches and request errors to assistive technology as well as visually. The WordPress REST documentation explains the data transport, not a complete accessible autocomplete pattern; consult current accessibility guidance when choosing markup and interaction details.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #3
When and how to register a custom endpoint
Use a custom route if the built-in search route cannot express the content or behavior you need. WordPress’s custom endpoint guide covers route registration, arguments, callbacks, permission callbacks and use of query classes such as WP_Query. Register the route on rest_api_init, and give it a unique namespace and version, following a pattern such as vendor/v1, to reduce route collisions and leave room for future changes. See Adding custom endpoints.
Keep the endpoint response narrowly shaped for the widget: return only the fields the interface needs, such as a display label and a link. Define and validate the accepted arguments, and make the callback perform only the intended search. A custom route is not automatically private just because it is custom; its permission callback must reflect what the visitor is allowed to access.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Keep public suggestions separate from restricted content
WordPress documents that public content is generally available through the REST API, while private and password-protected content requires authentication or explicit exposure. A public visitor-facing autocomplete should search only content intended for public discovery. When defining a custom endpoint, choose its permission callback deliberately; WordPress’s guide describes __return_true for public endpoints and notes that leaving out a permission callback produces a developer notice in current WordPress.
For logged-in REST API requests, WordPress cookie authentication uses a wp_rest nonce to help prevent cross-site request forgery, and the current user must have the capability needed for the action. Manual authenticated requests should send the nonce in X-WP-Nonce or through the documented parameter. A public, read-only search should not be made dependent on a logged-in user’s nonce. Details are in the REST API authentication guide.
Test the feature on the actual site
Before publishing, test the implementation with the site’s theme, plugins, API settings and installed WordPress version. Check:
- The API index and route schema, including accepted search parameters and returned fields.
- Empty, short, unusual and punctuation-heavy queries.
- Slow responses, failed requests, and a new query entered before an earlier request finishes.
- Whether drafts, password-protected items or other restricted content could appear.
- Mobile layout, keyboard-only use, focus movement and screen-reader announcements.
- That suggestion links open the intended content and the form still submits to the full search-results page.
The amount of work a custom endpoint or more specialized search solution warrants depends on your filters, content types, result presentation and expected search scale. If those needs exceed the built-in route, evaluate the additional maintenance and access-control requirements before adding a larger search system.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
