Instant Suggestions for Smart Search

An unofficial, portable WordPress plugin that adds accessible instant search suggestions powered by WP Engine Smart Search, with automatic fallback to native WordPress search.

The plugin enhances standard WordPress search forms without theme edits, direct Smart Search API calls, or exposed credentials.

Features

• Uses the existing WP_Query integration provided by WP Engine Smart Search.
• Displays up to four suggestions with title, content type, featured image, and permalink.
• Discovers public searchable post types automatically.
• Provides an admin screen for enabling and prioritizing content types.
• Supports classic and block-theme search forms, multiple forms, and dynamically inserted forms.
• Includes keyboard navigation and combobox/listbox ARIA semantics.
• Debounces requests, cancels stale requests, and uses browser, HTTP, and WordPress object caching.
• Falls back to native WordPress search when Smart Search is unavailable.
• Supports multisite with per-site configuration.

Requirements

• WordPress 5.7 or newer
• PHP 7.4 or newer
• WP Engine AI Toolkit/Smart Search 0.3.23 or newer for remote Smart Search results

The plugin remains functional without Smart Search by using native WordPress search.

Installation

1. Download the plugin ZIP from the latest GitHub release.
2. In WordPress Admin, open Plugins → Add New → Upload Plugin.
3. Upload the ZIP and activate Instant Suggestions for Smart Search.
4. Open Settings → Smart Search Suggestions.
5. Enable and order the public content types that should appear.

On first activation, all currently registered public searchable post types are enabled. Types registered later are discovered but remain disabled until an administrator enables them.

How it works

The public frontend sends a debounced request to:

GET /wp-json/instant-smart-search/v1/suggestions?q=example

The endpoint creates a normal public WP_Query. WP Engine Smart Search intercepts the query and performs remote matching and ranking. WordPress then hydrates the returned posts and formats the suggestion payload. If Smart Search cannot handle the query, WordPress completes it using native search.

Search promotions, custom results, synonyms, and semantic/hybrid settings configured in WP Engine AI Toolkit are respected automatically.

Configuration

The settings screen dynamically discovers post types that are:

• Public
• Publicly queryable
• Included in search

Attachments and internal WordPress types are excluded. Administrators can enable or disable whole content types and reorder their soft priority. Smart Search relevance remains the primary ranking signal.

Theme integration

Compatible search forms are enhanced automatically when they use standard WordPress markup such as:

<form role="search">
  <input type="search" name="s">
</form>

For a nonstandard search interface, initialize it explicitly:

window.InstantSmartSearch.init(inputElement, formElement);

Or dispatch the initialization event:

document.dispatchEvent(
  new CustomEvent('instant-smart-search:init', {
    detail: { input: inputElement, form: formElement }
  })
);

The frontend also dispatches:

• instant-smart-search:results
• instant-smart-search:selected
• instant-smart-search:error

WordPress filters

The following filters support custom integrations:

• instant_smart_search_enabled_post_types
• instant_smart_search_query_args
• instant_smart_search_candidate_limit
• instant_smart_search_result_limit
• instant_smart_search_result_payload

The default candidate count is eight and the default visible result count is four.

Performance and privacy

• Search begins after three characters and a 350 ms pause.
• Obsolete browser requests are cancelled.
• Smart Search responses are object-cached for five minutes.
• Native fallback responses are object-cached for 30 seconds.
• Public cache headers permit short browser and shared-cache reuse.
• No credentials, private content, drafts, passwords, custom analytics, or per-query database writes are exposed or created by this plugin.

Development

Validate PHP and JavaScript syntax locally:

find . -name '*.php' -not -path './vendor/*' -print0 | xargs -0 -n1 php -l
node --check assets/js/instant-suggestions.js
node --check assets/js/admin.js

Build an installable archive from the directory containing this repository:

zip -r instant-suggestions-for-smart-search.zip instant-suggestions-for-smart-search \
  -x '*/.git/*' '*/.github/*' '*/.DS_Store'

License

GPL-2.0-or-later. See LICENSE.

WP Engine and Smart Search are trademarks of their respective owners. This project is an independent integration and is not an official WP Engine plugin.