You can add predictive search to your theme so that suggested products appear immediately as you type into the search field. Predictive search helps customers articulate and refine their search queries, and provides new ways for them to explore an online store. It also lets them quickly browse matches without having to leave their current page to see a separate list of search results.
To add predictive search to your theme, you need to use the Shopify Ajax API. And because predictive search affects the appearance of your online store, it’s important to be familiar with the UI requirements and best practices before you implement it.
How product suggestions are generated
After you start typing into the search bar, predictive search suggests products that are related to what you’re typing. They match search terms either exactly or with typo tolerance.
Matching products or variants are returned as product suggestions that drop down from the search bar. For example, you’re looking for a snowboard and type
very-fast snowbo. Product suggestions appear for products or variants that contain
fast, and a term that begins with
If a word is separated by a hyphen or space, then it will be considered as two terms. Words or phrases that are separated into multiple terms return different results than a single term that includes the same words. For example,
t shirt return the same results, but
tshirt does not.
Product variants are returned only when the query matches terms specific to the variant title. Only the variants with the most matching terms are returned as results. For example, a store has a snowboard with a blue variant and a light blue variant. If you search for
blue snowbo, then both the blue and the light blue variants are returned. However, if you search for
light blue snowbo, then only the light blue variant is returned.
For products, search suggestions are based on the following properties:
- product type
For variants, search suggestions are based on the following properties:
- variant title
Predictive search includes typo tolerance, which lets search terms containing typos return the correct matching search results.
Typo tolerance is set to 1, which means that search displays results that differ from the search term by 1 letter, or results that have 2 letters in a different order. The first 4 letters of a search term need to be entered correctly for typo tolerance to take effect.
Predictive search uses a different search engine than storefront search. Because of this, they don't handle partial queries (incomplete words in search terms) in the same way.
Although predictive search supports partial queries, storefront search supports them only if the user searches with an asterisk (
*) at the end of their query. If you want to add full support for partial queries to your storefront search, then you can add prefix queries.
General requirements and limitations
Predictive search is supported only for themes that use the following theme languages:
A script tag in the
<head>section indicates whether predictive search is supported for the theme language:
<script id="shopify-features"></script>. This script tag includes a JSON-encoded
predictiveSearchkey with a boolean value. When it's set to
true, the theme language is supported, and predictive search is enabled. Otherwise, it's set to
Individual products can't be excluded from predictive search results. If a product has been hidden from SEO by using the metafield object, then it won't appear in predictive search results. To learn more, see The metafield object.
The API returns no more than 10 product suggestions per request.
UI requirements and best practices
Before you implement predictive search, make sure that you’re familiar with the following UI requirements and best practices. These include guidance for displaying products, styling the search field, and creating a search experience that is both accessible and mobile friendly.
|Number of products shown||
Limit predictive search results to 4-6 product suggestions on desktop. The number of suggestions to display can be flexible depending on the context where they appear.
The API doesn’t return more than 10 product suggestions, since displaying that much information can be potentially overwhelming and less relevant to the customer.
An ideal desktop search experience will not include so many results that scrolling is necessary. This is a frequent problem with sites that use this structure; often the content behind the modal is what responds to scrolling.
Include a close button. It should be in the form of an icon or text that leaves the search experience and closes the product suggestion dropdown. This action should not clear the query.
Include a search button. It should be in the form of an icon or text that takes the user to the search results page. Also achieved by clicking enter on a keyboard, or “go”/”search” on a mobile keyboard.
The query should stay in the search field until the customer explicitly clears the query or navigates to a different page. The used query should be repeated on the search result page.
Hide the empty-state drop-down when there are no product suggestions that match the query. The lack of feedback from predictive search should encourage customers to continue their search from the results page.
Focus the search field when tapping on the search icon. Reduce the number of interactions required to use search. If a user taps the search icon, then focus the search field and ensure that they are able to begin searching immediately.
Allow scrolling within the drop-down. When displaying product suggestions, make sure that the user is able to scroll through the results.
|Browser and mobile autocomplete||
Disable browser-based autocomplete and search history, and mobile OS text autocorrect and autocomplete.
Expose only the information essential to the customer’s search. To maintain a streamlined and consistent experience, search interface content and product data should be reduced to the minimum amount necessary to communicate how the feature works and to make the selection of products meaningful. The API supports your ability to control which elements are exposed or hidden. Although you can adapt this to the needs of the merchant, it is recommended that you expose only the image, product title, and price.
Don’t show a "Sold out" label for suggested product variants in case the user is looking for a variant that isn’t sold out. "Sold out” should be shown only when the product object within the response has its
Use a heading to label product suggestions to help users anticipate the type of results they can expect. For example, use a "Products" heading for product suggestions.
Include a clear button. Clear button or text in the search field to delete any query entered.
Display the search field, or at least the search icon, in the header of all pages. If search is a significant element of the overall experience you want to provide, then make sure that it’s displayed prominently.
For stores with only one product or a small number of products, the search field can be located within a hamburger menu.
|"More results" links||
Display a link in the list of product suggestions to indicate that there might be more results on the search results page. For example, the link could include the text "Search for [your query]" (where [your query] is what the user has entered in the search field) or "View all results."
Example search patterns
The following layouts and patterns can help you implement predictive search effectively in your theme.
Inline search drop down
Desktop: inline search
The search dropdown overlays the page, without taking up too much visual space.
Mobile: inline search
Desktop: in-menu search
The search dropdown overlays the page, without taking up too much visual space.
Predictive search results appear under the search field in the menu.
Alternatively, the search field can be positioned at the top of the menu. In this case, product suggestions would overlay the menu list (see the in-menu mobile example for this layout).
Mobile: in-menu search
Requesting predictive search results from the Ajax API
You can access predictive search results by making requests to the
/search/suggest.json? endpoint in the Shopify Ajax API. The API responds with JSON, and doesn't require custom Liquid. To learn how this endpoint works, see Shopify Ajax API.
Get predictive results for a specified search query. Predictive search currently supports suggestions for products only, and provides suggestions based on the titles of available products and variants, the product type, and the vendor.
||String||The search query.|
||Array||Specifies the type of results requested. Currently supports
||String||Specifies whether to display unavailable product results. The three possible options are
||Integer||Limits the number of results returned. Default:
Example call using jQuery:
Example call using Fetch:
Example call using Predictive Search Library
You can find the Predictive Search Library as part of the Shopify/theme-scripts GitHub repository.
Theme settings settings_schema.json
Global settings example:
All errors related to the request parameters are returned with a 422 status code and a relevant error message. The
description field describes the request error.
If your theme isn't using one of the supported languages listed above, then the API returns the following error:
Exceeding the request throttle limit will return a 429 status code with a relevant error message.
In this case, the response will also contain an HTTP header with the Retry-After value in seconds.
All other unexpected errors will return a 5xx status code.