All Tutorials

Predictive search

All Tutorials

Predictive search

Predictive search

You can add predictive search to your theme so that suggested results 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.

Example of search dropdown showing recommended products

Predictive search supports suggestions for products, collections, pages, and articles.

To add predictive search to your theme, you need to use the Ajax Predictive Search 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 suggestions are generated

The predictive search dropdown displays the following information when you enter a query.

Diagram of search dropdown

Legend for the diagram of the search dropdown
Point Description
1Predictive search dropdown
2Product suggestions
3Collection suggestions
4Page suggestions
5Article suggestions

After you start typing into the search bar, predictive search suggests results that are related to what you’re typing. They match search terms either exactly or with typo tolerance on searchable properties of shop resources.

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 very, fast, and a term that begins with snowbo.

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 and 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 snowbo, then Snowboard product will be returned. However, if you search for light blue snowbo, then only the light blue variant is returned.

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.

UI requirements
Number of resources shown

The predictive search API returns a maximum of 10 results per resource type. For example, for a query that matches on both products and pages, the API returns a maximum of 10 matching product resources and 10 matching page resources. However, if the query returns matches for multiple resource types, then consider tailoring responses to include a mix of resources. Limit the overall number of suggestions to avoid overwhelming the user or taking up too much space on the screen. Also, you can adjust the number of suggestions to display depending on the context where they appear.

Close action

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.

Search action

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.

Clearing query

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.

Empty state

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.

Mobile interactions

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.

Accessibility requirements
Browser and mobile autocomplete

Disable browser-based autocomplete and search history, and mobile OS text autocorrect and autocomplete.

  • Desktop: users’ search history from across the Web is frequently displayed within a dropdown that overlays the on-site predictive search dropdown. This can disrupt both the UI and the overall search experience.
  • Mobile: when the search field is in focus in order to prevent two different autocomplete logics from competing with one another.
Best practices
Resource information

Expose only the information essential to the customer’s search. To maintain a streamlined and consistent experience, reduce search interface content and resource data to the minimum amount necessary to make selection meaningful. Using the API, you can control which elements are exposed or hidden. Although you can adapt this to the needs of the merchant, you should consider only exposing these recommended fields:

Product fields
  • image
  • product
  • title
  • price
Collection fields
  • title
Article fields
  • title
Page fields
  • title

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 available attribute set to false, which means that all variants are either unavailable or sold out.

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.

Search visibility

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

The search dropdown overlays the page, without taking up too much visual space.

Example of in-line search in desktop. The search bar is visible on the site.
Example of in-line search in desktop. Predictive search appears as a dropdown under the search field.

Example of in-line search in desktop.

The search dropdown overlays the page, without taking up too much visual space.

Example of in-menu search in desktop. No search bar is visible on the site.
Example of in-menu search in desktop. Search appears in the menu.

Example of in-menu search in desktop.

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).

Example of in-menu search on mobile.

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 the Predictive Search API.

Example using Predictive Search Library

To help implement Predictive Search in your theme, you may want to use the Predictive Search Library which part of the Shopify/theme-scripts GitHub repository.

import PredictiveSearch from "@shopify/theme-predictive-search";

var predictiveSearch = new PredictiveSearch({
  resources: {
    type: [PredictiveSearch.TYPES.PRODUCT],
    limit: 4,
    options: {
      unavailable_products: PredictiveSearch.UNAVAILABLE_PRODUCTS.LAST,
      fields: [

// Set success event listener
predictiveSearch.on("success", suggestions => {
  const productSuggestions = suggestions.resources.results.products;

  if (productSuggestions.length > 0) {
    var firstProductSuggestion = productSuggestions[0];

    alert(`The title of the first product suggestion is: ${

// Set error event listener
predictiveSearch.on("error", error => {
   console.error("Error message:", error.message);

// Send query
predictiveSearch.query("The Calling");

Theme settings settings_schema.json

Global settings example:

    "name": "Search",
    "settings": [
        "type": "checkbox",
        "id": "predictive_search_enabled",
        "label": "Enable product suggestions",
        "info": "This will also affect the search field on the search page."
        "type": "checkbox",
        "id": "predictive_search_show_vendor",
        "label": "Show vendor"
        "type": "checkbox",
        "id": "predictive_search_show_price",
        "label": "Show price"