Search Bar & Autocomplete¶

The search bar is a placeable storefront extension that gives shoppers a modern, as-you-type search experience: an instant dropdown of matching products and categories, the ability to jump straight to a product or to the full results page, and an optional animated "typewriter" placeholder that hints at popular searches.

It sits on top of the same Typesense-backed platform as the /search results page and /c/** browse pages (see Search Architecture), so suggestions always match what the full search returns.

What the shopper sees¶

Instant results — as soon as the shopper has typed the minimum number of characters, a dropdown shows product hits (thumbnail, name, brand, price/sale price), matching categories and — on sites with Content Search — matching pages and articles with a highlighted snippet.
Jump straight there — clicking a product goes to its page; clicking a category goes to that browse page; the "See all results for …" footer (or pressing Enter, or submitting the form) goes to the full /search results page.
Full keyboard control — ↑/↓ move through suggestions, Enter opens the highlighted one, Esc closes the dropdown.
Works without JavaScript — the box is a plain GET /search form, so search still works if the enhancement script doesn't load. The dropdown is pure progressive enhancement.
Mobile — collapses to a search icon that opens a full-width search sheet.

How it works¶

Piece	Where
Extension	`SearchBarExtension` (commerce-core) — renders into the `searchMenu` nav slot
Templates	`templates/{nova,bootstrap}/extensions/searchBar/main.html`
Enhancement script	`themes/{nova,bootstrap}/js/extensions/searchBar/searchBar.js`
Suggest endpoint	`GET /search/suggest?q=…` → `SearchSuggestController` (web-mvc)
Product suggestions	`MerchandisingQueryService.suggest(...)` — read straight off Typesense hits, no Mongo round-trip
Category suggestions	`MerchandisingTreeService.suggestNodes(...)` — non-hidden primary-tree nodes matching the term
Page & article suggestions	`ContentQueryService.suggest(...)` — only for sites with Content Search enabled

The script calls the same-origin /search/suggest endpoint (debounced, with in-flight requests cancelled) and renders the JSON response. Because product suggestions are built directly from the indexed Typesense documents, a keystroke costs a single search round-trip and nothing more.

Adding it to a site¶

The search bar is a slot-placed extension (not global) so operators decide where it appears. It is seeded into the searchMenu slot of the default storefront stereotypes (defaultProduct, variantProduct, defaultCollection, defaultPage, merchandisingNode, blogPage, blogPost, thirdPartyFundraiser), so a freshly initialised site has it in the header out of the box.

Existing sites (whose stereotypes pre-date this feature) add it via the admin extension editor: edit a stereotype (or an individual page/product/collection), add the searchBar extension, and place it in the searchMenu slot. The nav fragment renders whatever is in that slot.

Configuration¶

Configured per placed instance in the admin extension editor:

Field	Default	What it does
Placeholder text	(blank → site default)	Static placeholder; blank uses the `search.placeHolder` message.
Animate placeholder (typewriter)	Off	When on, the placeholder types out each phrase below in turn. Honours `prefers-reduced-motion` and pauses while the shopper is typing.
Typewriter phrases	(blank)	Comma-separated curated phrases the animation cycles through, e.g. `winter coats, running shoes, gift ideas`. Only used when the typewriter is on.
Show product suggestions	On	Show the products section in the dropdown.
Show category suggestions	On	Show the categories section in the dropdown.
Max product suggestions	6	Cap on product hits (server clamps to 12).
Max category suggestions	4	Cap on category hits (server clamps to 8).
Show page & article suggestions	On	Show matching content pages and blog posts. Only has an effect on sites with Content Search enabled.
Max page & article suggestions	3	Cap on page hits (server clamps to 8).
Minimum characters before suggesting	2	How many characters before the dropdown starts fetching.

Theming¶

Nova is the primary, richly-styled target. The Bootstrap template is a functional fallback that reuses the same markup hooks and the same enhancement script, so the extension never renders blank on legacy/hardware themes. Both follow the platform's theme-fallback rule — a Nova site uses the Nova template; anything else falls back to Bootstrap.

Accessible label¶

The box's accessible label reads "Search products" on a shop and "Search this site" when the site config key storefront-commerce-chrome-enabled is off (message keys search.label.products / search.label.site; the placeholder is configured separately and is not affected). See Brock theme.