SScale Themedocs
FR

Real-time suggestions with product, collection, and page results. Highlight matching, debounce, and caching.

Predictive Search

Scale Theme's predictive search displays real-time suggestions as soon as the visitor starts typing. Results include products (with images and prices), collections, and pages, all without reloading the page.

How it works

  1. The visitor clicks on the search icon in the header
  2. The search field opens (overlay or inline depending on configuration)
  3. As soon as they start typing (from 2 characters onward), suggestions appear
  4. Results update in real time with each keystroke
  5. The visitor can click on a result or press Enter to see all results

Result types

TypeDisplayInformation
ProductsThumbnail + title + priceUp to 6 products
CollectionsCollection titleUp to 3 collections
PagesPage titleUp to 3 pages

Product results

Each product displays:

ElementDescription
ImageProduct thumbnail (first image)
TitleProduct name with search terms highlighted
PriceCurrent price (and compare-at price if applicable)
VendorManufacturer name (optional)
ℹ️Product results are the most visually rich. They always appear first in the suggestion list, as they are the most likely to lead to a purchase.

Search term highlighting

Search terms are automatically highlighted in the results. If the visitor types "black dress", the words "black" and "dress" will be bolded in the matching titles.

Performance

Predictive search uses several optimizations for near-instant results:

Debounce

Requests are sent with a 300ms debounce. This means the request is only sent 300ms after the visitor's last keystroke, avoiding a request for every single character.

AspectDetail
Debounce delay300ms
Minimum characters2 before the first request
Concurrent requestsPrevious requests are canceled if a new one is triggered

Cache

Search results are cached in memory for previously searched terms:

AspectDetail
StrategyIn-memory cache (session)
DurationUntil the page is closed
KeyExact search term
InvalidationAutomatic on navigation
💡Thanks to caching, if a visitor types "dress", deletes the text, then retypes "dress", the results display instantly from cache, without a new server request.

Settings

SettingDescriptionOptions
EnableEnables predictive searchYes / No
Number of productsProducts displayed2 - 8
Show collectionsInclude collectionsYes / No
Show pagesInclude pagesYes / No
Show vendorManufacturer name below the titleYes / No
Show pricePrice next to the productYes / No

Search opening style

SettingDescriptionOptions
Opening styleHow the search opensOverlay / Inline / Full screen
StyleDescription
OverlayA search panel opens as an overlay above the content
InlineThe search field expands within the header
Full screenThe search takes over the entire screen (mobile-first)

Keyboard navigation

KeyAction
Down arrowNavigate to the next result
Up arrowNavigate to the previous result
EnterOpen the selected result (or launch the full search)
EscapeClose the predictive search
TabMove to the next result

Mobile behavior

AspectDesktopMobile
OpeningOverlay or inlineFull screen
ResultsGrid with large imagesCompact list
KeyboardArrow key navigationTouch keyboard with suggestions
CloseEscape / Click overlayBack button / Swipe

Shopify API

Predictive search uses Shopify's native Predictive Search API (/search/suggest.json). Results are filtered and formatted on the client side.

ParameterValue
Endpoint/search/suggest.json
MethodGET
Typesproduct, collection, page
LimitConfigurable per type
⚠️Shopify's Predictive Search API has a limit of 10 requests per second per store. The 300ms debounce ensures this limit is never reached under normal usage.

Best practices

  1. Always enable it: Predictive search is a standard that visitors expect. Disabling it hurts the experience
  2. 6 products: This is the optimal number of product results. Enough to find what you're looking for, not so many as to overwhelm
  3. Enable collections: Collections help visitors find entire categories, not just individual products
  4. Test common terms: Verify that the most frequent searches for your store return relevant results
PreviousAnnouncement BarNextBreadcrumb