Appearance
Search
Uisce includes predictive search with instant results as visitors type, and a full search results page at /search. Predictive search is always on and needs no section settings — the only thing it reads is the Storefront API token in Theme settings. Everything else lives in the Search section on the /search template.
What it looks like
Here's the search feature alongside its settings. The left panel shows what you'll see in Customize (Search section), and the right shows the predictive search dropdown in action.
Predictive search preview
Settings
Search settings live in two places in the theme editor. The Header section has none — predictive search is always on.
Theme settings
Open Customize → Theme settings → Storefront API.
| Setting | What it does |
|---|---|
| Storefront Access Token | Storefront API token that enables native typo tolerance. See token setup below. |
Search section settings
These control the /search results page. Open Customize → navigate to /search → click the Search section.
| Setting | What it does |
|---|---|
| Color scheme | Which of your four colour schemes the search results page uses. |
| Enable filtering | Shows a filter sidebar on the results page so visitors can narrow by product type, price, color, and more. |
| Enable sorting | Shows a sort selector on the results page. |
| Results per page | Number of results per page (8–48, default 20). |
| Suggested collections | Up to 4 collections shown in the zero-results empty state to guide visitors toward relevant sections. |
| Popular search 1–5 | Up to 5 search terms shown in the zero-results empty state on the search results page. |
Set up the Storefront API access token
To enable native typo tolerance (e.g. "shrt" → "shirt"), you need a Public Storefront Access Token. Without a token, predictive search still works via Shopify's REST endpoint — results appear, but typo tolerance is unavailable.
Shopify requires you to create the token manually — it cannot be done automatically by the theme.
Step 1: Create a Headless channel or Custom App
- Shopify admin → Settings → Apps and sales channels → Develop apps (or Headless)
- If no Headless channel exists: click Add a Headless sales channel → Install
- If using a Custom App: go to the app's API credentials
Step 2: Create a Storefront Access Token
Via Headless channel:
- Headless → Storefronts → Add a new Storefront → Create → copy the Public Storefront API token
Via Custom App:
- Admin → Apps → [Your app] → API credentials → Storefront API → Create token → copy the token
Step 3: Add the token to your theme settings
- Shopify admin → Online Store → Themes → Customize → Theme settings → Storefront API
- Paste the token into the Storefront Access Token field
- Save
Alternatively, set current.storefront_access_token in config/settings_data.json via the code editor.
Verify the token is active
Open any page on your store → browser DevTools → Console → paste the diagnostic snippet. Look for:
token: true
predictiveSearchBackend: "graphql"The backend flag is written server-side from the token field alone: graphql when the token is filled in, rest when it is blank. So token: false with predictiveSearchBackend: "rest" means no token is configured — paste one in and save. The flag never changes at runtime, so a graphql value with missing results points at the token itself: check it is for this store and has not been revoked.
What predictive search finds
Predictive search looks across your entire store and groups results by type:
- Products — Matching products with images and prices
- Collections — Collections whose names match the search query
- Pages — Matching pages (About, FAQ, etc.)
- Articles — Matching blog posts
Results update with every keystroke. Pressing Enter submits the search form and opens the full /search results page — unless the visitor has arrow-keyed down to a suggestion, in which case Enter goes straight to that result.
What visitors see before typing
When a visitor focuses the search bar without typing, the drawer shows their recent searches — the last 5 terms they submitted, kept in browser storage on their device until they clear them. One Clear all button empties the list; there is no per-term dismiss. Popular searches do not appear here — they belong to the search results page.
What visitors see while typing
- Results grouped by Products, Collections, Articles, and Pages (up to 4 per group)
- Typo-tolerant results when a Storefront API token is configured
Typed tabs on the search results page
The /search results page renders tabs — Products, Articles, Pages — based on what the search query returns. Tab behavior:
- Tabs only appear when the corresponding type has at least one result
- Switching tabs updates the URL with
?type=products,?type=articles, or?type=pagesvia the browser History API (shareable, back/forward work) - Filters on the Products tab scope to products; switching to Articles clears product-specific filters
No settings control which tabs appear — they are driven by search results. To ensure articles appear, make sure your blog posts are published.
Zero-results empty state
When a search on the /search page returns no results, the page shows:
- A did-you-mean chip, when a Storefront API token is configured and the API returns a query suggestion
- Up to 4 suggested collections (configured in the Search section settings)
- Popular search terms (configured in the Search section settings)
Populate the last two to give visitors a clear path when their search finds nothing.
The predictive drawer has its own no-results state: a "no results" headline, the visitor's recent searches, and the same did-you-mean chip. Tapping the chip re-runs the search with the suggested spelling.
Before you go live
- [ ] Storefront Access Token configured (Theme settings → Storefront API → Storefront Access Token)
- [ ] Verify typo tolerance: search for a misspelled product term — corrected results should appear
- [ ] Popular searches configured for your niche (Search section →
popular_search_1–popular_search_5) - [ ] Suggested collections configured for the zero-results empty state (Search section)
- [ ] Test typed tabs: search for a term with product and article results — tabs appear; tab swap updates the URL
- [ ] Test recent searches: search for a term → clear query → focus search again — the term appears in recent searches
Related guides
- Search support — token diagnostics, typed-tab issues, predictive search debugging
- Translations
- Theme settings