Search-as-you-type Blocks

AI Search ships two optional Gutenberg blocks that add search-as-you-type to any WordPress site. Both are opt-in – the plugin still improves your existing search bar even if you never touch a block editor – but if you want a live dropdown of results as visitors type, these are the blocks you drop in.

The two blocks

AI Search Box

A search field with a live dropdown that shows thumbnail, title, and (on WooCommerce sites) price. Results appear as the visitor types keyword matches, then the AI matches join once the visitor pauses. Fits well on any page, in a sidebar, or inside a template part.

AI Search Button

A search icon that opens a full-screen overlay when clicked. Same live dropdown mechanics as the search box, but hidden behind a single icon – useful in a compact site header where a search bar would eat too much horizontal room.

How to add a block

  1. Edit any page, template, or header in the WordPress block editor.
  2. Click the + button and search for AI Search.
  3. Pick either AI Search Box or AI Search Button.
  4. Save. That is it. Both blocks work out of the box with no configuration.

Two-phase live search

Both blocks run search in two phases as the visitor types, and the split is deliberate:

  • Keyword phase – fires 180ms after each keystroke. Uses your existing keyword index and costs zero embeddings, so typing is effectively free. Results appear near-instantly.
  • AI phase – fires 400ms after the visitor stops typing. Sends one embedding request and merges semantic matches below the keyword results. A small “AI suggestions” label separates them so the visitor knows what they are looking at.

The result: fast, cheap keystrokes with a slower but smarter pause. If the visitor keeps typing, the AI request is cancelled before it fires, so you never pay for embeddings the visitor did not intend to complete.

Block settings

Select either block in the editor and use the right sidebar to change:

  • Placeholder text – the greyed-out prompt inside the input.
  • Post types – restrict results to specific types (e.g. posts only, products only). Defaults to whatever the plugin considers searchable.
  • Max results – dropdown items to show. Default 8, capped at 8 even if you set it higher.
  • Show thumbnails – toggle the small featured image in each row.
  • Show prices – WooCommerce sites only; toggles the price line under the title.
  • Accent color – the highlight color used for hover state and the “AI suggestions” label. Reads a CSS variable from your theme by default; override in the sidebar.

Result badges

Behind each dropdown row is a small badge indicating which tier surfaced the result: Exact Match, Keyword Match, or AI Match. By default these badges show only to logged-in editors (so you can debug your own catalogue) and are hidden from anonymous visitors. Toggle public visibility in AI Search → General → Show AI badge to visitors.

Where to use each

  • Header (small icon) – use AI Search Button. Put it in your header template part so it appears on every page.
  • Landing pages / documentation index – use AI Search Box. Wider input, more inviting for a first search.
  • WooCommerce product archive – use AI Search Box in a sidebar. Restrict post types to product. Great for catalogue exploration.
  • Both together – fine. The button is a compact fallback, the box is the primary entry point on marketing pages.

Performance and cost notes

Every visitor keystroke costs 0 embeddings. Only a paused query (400ms of no typing) triggers exactly one embedding request against the AI Search Service or your OpenAI API key. Rate limit: 30 requests per minute per IP hash, cached for 5 minutes per query. Minimum query length: 3 characters.

The endpoint used by the blocks is the plugin’s own REST route: GET /wp-json/ai-search/v1/suggest. Full 3-tier logic applies – the dropdown honours exact matches, keyword matches, and semantic matches in that order, exactly like the site search does.

Localisation

Frontend strings (“Search”, “No results”, “AI suggestions”) are passed from PHP to JS via a data attribute, so they follow your site locale. The plugin ships translated catalogs for pt_PT, es_ES, and fr_FR; other locales fall back to English.

Last updated: September 2026. Applies to AI Search 1.33.0 and later.

← Back to Documentation