This guide covers two related surfaces:
| Surface | When customers see it |
|---|---|
| Search overlay | A predictive search panel that opens when the customer clicks the search icon in the header |
| Search results page | The full /search page, reached after the customer submits a search query |
The search overlay is for fast, in-page suggestions while typing. The search results page is for browsing complete results with filters and sort.
Search overlay (predictive search)
When customers click the search icon in the header, the search overlay opens as a modal panel.
What the overlay shows
| State | Content |
|---|---|
| Empty (no query yet) | Recent searches, trending products |
| Typing | Live product suggestions powered by Shopify's /search/suggest.json API. Results update as the customer types |
| No results | A message and the trending products list |
Recent searches
The overlay stores up to 5 of the customer's most recent search queries. The list lives in the browser's local storage under the key fitcore-recent-searches and persists across visits in the same browser.
Customers can clear individual entries or clear the whole list. The list is per-browser, not per-Shopify-customer-account.
Trending products
The trending list shows up to 4 products from your collections.all.products (the default Shopify "all products" pool, ordered by Shopify's default sort). This list is server-rendered into the page, so it is the same for every customer regardless of their query history.
There are no settings for trending products in the theme editor. To change which products appear, change the order or visibility of products in your Shopify admin (which affects the all collection).
Predictive search results
While the customer types, the overlay calls /search/suggest.json and renders the results returned by Shopify's predictive search engine. The request asks for products, collections, pages, articles, and query suggestions, so a query can return any of these types. Each result shows what is appropriate for its type (image, title, price for products; image, title for collections; title for pages and articles).
Customers can click a result to go directly to that page, or submit the form to go to the full search results page.
The predictive search engine is controlled by Shopify, including which items are matched, how relevance is scored, and what happens with synonyms. Configure synonyms and search rules in the Shopify Search and Discovery app.
Search results page
When customers submit a search (from the overlay, the search bar, or any other form pointing to routes.search_url), they land on the search results page at /search.
What ships on the search page
The default template contains one section:
| # | Section | Purpose |
|---|---|---|
| 1 | Search | The unified search results page: type filter pills, search box, sort, optional faceted filters, and the results grid |
Search section settings
In the theme editor, navigate to the search results page (search for any term to populate the preview) and click the Search section.
| Setting | Range or options | Default | What it controls |
|---|---|---|---|
| Color scheme | All schemes | Scheme 1 | Color scheme applied to the section |
| Products per page | 8 to 48 in steps of 4 | 24 | How many results to show per page |
| Columns on desktop | 2 to 5 | 4 | Result grid columns on screens 990px and wider |
| Columns on mobile | 1 or 2 | 2 | Result grid columns on screens narrower than 750px |
| Use filtering | On | Show faceted filters when viewing product results | |
| Filter layout | Sidebar, Drawer | Sidebar | Sidebar shows filters in a column on desktop. Drawer shows a button that opens a slide-in filter panel |
| Show type filters | On | Show the All/Products/Articles/Pages tabs at the top of the toolbar | |
| Show sort | On | Show the sort dropdown | |
| Empty state collection | Empty | Optional. A collection picker. When set, the no-results state shows up to four products from this collection as suggestions | |
| Padding top | 0 to 100 px in steps of 2 | 40 | Space above the section |
| Padding bottom | 0 to 100 px in steps of 2 | 40 | Space below the section |
Type filter tabs
When Show type filters is on, four tabs appear at the top of the toolbar:
| Tab | What it shows |
|---|---|
| All | Combined results from products, articles, and pages |
| Products | Product results only. Faceted filters are also available on this tab |
| Articles | Blog article results only |
| Pages | Page results only |
Each tab is a separate URL (using the type URL parameter). Customers can bookmark a tab or share a filtered URL.
Filters on the search page
Faceted filters appear on the search page only when:
- Use filtering is on AND
- The customer is on the Products tab AND
- Shopify returns at least one filter (the search has fewer than 1,000 product matches; Shopify does not provide filters above this limit)
The 1,000-product limit is set by Shopify, not by Fitcore. For very broad searches that match more than 1,000 products, Shopify returns no filters and the page shows results without filtering. Customers can narrow the search by typing more specific queries.
When filters are available, they work the same way as on the collection page (powered by Shopify's native filtering, configured in the Shopify Search and Discovery app). See template-collection.md for details.
Sort options
When Show sort is on, the sort dropdown shows seven options:
| Sort option | URL parameter |
|---|---|
| Relevance (default) | sort_by=relevance |
| Price: low to high | sort_by=price-ascending |
| Price: high to low | sort_by=price-descending |
| Alphabetical: A to Z | sort_by=title-ascending |
| Alphabetical: Z to A | sort_by=title-descending |
| Date: new to old | sort_by=created-descending |
| Date: old to new | sort_by=created-ascending |
Sort applies across the entire result set, not just the current page (this differs from the collections list page). The page reloads with the sort applied via Shopify's server-side sorting.
Result rendering
Each result type renders differently in the grid:
| Type | Card content |
|---|---|
| Product | Standard product card (image, title, price, swatches, quick add). Same as collection page |
| Article | Image, type label "Articles", title, excerpt (100 character truncation), publish date |
| Page | Placeholder image, type label "Pages", title, content excerpt (100 character truncation) |
Other Shopify object types (such as collections) are not rendered as result cards in this version.
Empty state and no results
Two distinct states:
No search performed. The customer arrived at /search without a query. The page shows a search prompt heading, a short description, and a search form for entering a query. No products are rendered in this state on the live storefront. In the theme editor, the empty state collection can be previewed: design mode renders up to four products from the chosen collection so merchants can verify their selection. This preview is editor-only.
No results for query. The customer searched but Shopify returned zero matches. The page shows a "no results" message that includes the search term and suggestions to try a different query. If an empty state collection is set, four products from that collection appear below the message as a fallback browsing aid. This grid is shown on the live storefront in this state.
To customize the empty state copy, edit the locale strings under Online Store, Themes, Edit default theme content, Search.
Pagination
The search page uses Shopify's standard pagination via {% paginate search.results by N %}. Numbered pagination with previous and next links appears at the bottom when results exceed the products per page setting.
There is no load more or infinite scroll mode for the search page.
Search box behavior
The search box appears in three places:
| Location | Form action |
|---|---|
| Header search icon (opens overlay) | Submits to routes.search_url |
| Inline search box on the search results page (toolbar center) | Submits to routes.search_url |
| Inline search box in the no-results state | Submits to routes.search_url |
All three submit to the same Shopify endpoint. The query is preserved in the URL through ?q=.
Multi-language and multi-currency
- Search results respect the customer's selected language: products, articles, and pages translated through Shopify's translation system appear in the customer's language when relevance matches.
- Search relevance and synonyms are configured in the Shopify Search and Discovery app where supported.
- Prices in product results update automatically based on the customer's selected market and currency.
- Type filter labels and sort option labels follow the customer's language through the theme's locale files.
See markets-localization.md for the full localization workflow.
Performance considerations
- Predictive search calls
/search/suggest.jsonafter a short typing delay to avoid request flooding. The first request may be slightly slower while Shopify warms its cache. - The trending products list is server-rendered, so it does not add a client request when the overlay opens.
- Results page pagination at 24 per page balances initial load with completeness. For stores with very large catalogs, consider whether 16 or 20 might be a better fit.
What to do next
| If you want to | Read |
|---|---|
| Configure search rules and synonyms | Use the Shopify Search and Discovery app (covered in filtering-and-discovery.md) |
| Set up the cart drawer | template-cart.md |
| Configure the home page promo and slideshow | sections-hero-and-slideshow.md |
| Set up trust badges below search results (optional, requires adding the section) | sections-promotional.md |
End of template-search.md.