Storefront Search

Storefront Search adds a smarter search experience to your storefront's own search bar: shoppers get instant query suggestions as they type, results that understand synonyms, translations, and product specs (not just exact keyword matches), and simple in-stock / price filters — all styled with your own HTML, injected into your existing page.

It's for stores that want a better search box than "type a word, hope it matches a product title exactly" — especially catalogs with lots of variants, multiple languages, or shoppers who don't type your exact product names.

The feature is configured per business from the dashboard's Storefront Search settings page, and delivered through a small embeddable script that binds to HTML you write — no separate widget UI to learn, no iframe.

Not to be confused with: the dashboard also has a Product Search Settings page, which tunes what products the AI shopping consultant recommends inside chat conversations. That's a different feature — this page is about the search bar on your storefront pages.

How it works

Two things happen depending on what the shopper is doing:

• While typing — an instant "as you type" panel shows query suggestions, a handful of top-matching products, and category/brand chips, all from one lightweight lookup. No AI call yet, so it stays cheap and fast on every keystroke.
• On submit (Enter, clicking the search button, or picking a suggestion) — the full search runs: it matches on keywords, understands what was searched for (synonyms, translations, specs like color or brand), ranks by both textual and semantic similarity, and combines the two into one ranked list.

A couple of behaviors worth knowing about:

• Smart matching, not just exact keywords. Search understands synonyms, cross-language names (e.g. Greeklish/Greek), and normalized specs once your catalog has gone through enrichment (see below). Catalogs that haven't been enriched yet still search fine on their existing text — enrichment widens recall, it doesn't gate search.
• Rarely zero results. If a query is too narrow (a typo, an overly specific phrase) and turns up too few matches, the system automatically relaxes it and returns the closest matches instead of an empty page. The SDK flags these as relaxed, so a template can label them "Similar products" instead of presenting them as exact hits.
• Filters re-run the last search. In-stock and price filters apply to whatever query was last searched, not to your full catalog.

Configuration reference

Testing

Before enabling on a live storefront, use the dashboard's live preview — it's wired to the real search pipeline for your business, so typing and submitting a search queries your actual catalog. Sample product cards fill the results grid until you run your first search, so you can check the visual design without needing a working query yet.

If a template is missing a required marker, the preview shows a warning underneath it (e.g. "Search bar template is missing data-octocom-search-input") so you can catch mistakes before saving.

Best practices

• Start from the examples. Every tab is pre-filled with a working template — tweak colors and spacing rather than starting from a blank editor, so you don't accidentally drop a required marker.
• Templates are cloned, not rendered directly. Don't rely on the original template element being visible on the page — it stays hidden/detached; only its clones are shown.
• Rebuild the lexicon after catalog changes. Facet suggestions and query understanding go stale otherwise.
• Enrich before judging search quality. An un-enriched catalog will look weaker on synonym/translation queries — run enrichment before concluding search "doesn't find" something.
• Use replace for the search bar and results grid unless you specifically want to keep your store's native element alongside ours — most integrations replace the native search box/grid entirely.
• Test filters together with a search, not in isolation — filters re-run whatever was last searched, so an empty query with a filter applied returns nothing.