Appearance
Search
Uisce includes predictive search with instant results as visitors type, and a full search results page at /search. Predictive search settings live in the header section; search results page settings live in the Search section.
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.
Header section settings
These control the predictive search drawer. Open Customize → Header section to find them.
| Setting | What it does |
|---|---|
| Show predictive search | Enables the instant-results drawer that appears when visitors type in the search bar. On by default. Turn off to use only the full /search results page. |
| Storefront Access Token | Storefront API token that enables native typo tolerance. See token setup below. |
| Popular searches 1–5 | Up to 5 search terms shown when a visitor focuses the search bar without typing anything. Leave blank to hide the popular searches block. |
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 filters | 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 1–4 | Collections shown as cards in the zero-results empty state to guide visitors toward relevant sections. |
| Popular searches 1–5 | Popular search terms shown in the zero-results empty state. |
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 → Search section
- 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: "storefront-api"If token: false, the token field is blank. If predictiveSearchBackend: "rest", the token is set but the Storefront API returned an error — check that the token is for the correct 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 or clicking View all results opens the full /search results page.
What visitors see before typing
When a visitor focuses the search bar without typing:
- Recent searches — their last 5 searches (stored in browser storage per session), each with a dismiss button
- Popular searches — the terms you configured in the Header section settings
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
- A did-you-mean chip when the API returns a query suggestion
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 returns no results, the page shows:
- Up to 4 suggested collections (configured in the Search section settings)
- Popular search terms (configured in the Search section settings)
Populate both to give visitors a clear path when their search finds nothing.
Before you go live
- [ ] Storefront Access Token configured (Theme Settings → Search → Storefront Access Token)
- [ ] Verify typo tolerance: search for a misspelled product term — corrected results should appear
- [ ] Popular searches configured for your niche (Header section →
popular_searches_1–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