We're constantly trying to improve your support experience, and your feedback is extremely valuable to us.

Please take a moment to tell us about your experience today.
Sign up for future Help Center user research studies.

Predictive search

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.

Example of search dropdown showing recommended products

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

Searchable properties

For products, search suggestions are based on the following properties:

  • title
  • vendor
  • product type

For variants, search suggestions are based on the following properties:

  • variant title

Typo tolerance

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.

Partial queries

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:

    • Danish
    • Dutch
    • English
    • French
    • German
    • Italian
    • Portuguese
    • Spanish
  • 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 predictiveSearch key 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 false.

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

UI requirements
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.

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
Product information

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.

Labels

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.

Actions

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 Shopify Ajax API.

GET /search/suggest.json?

GET /search/suggest.json?s=<query>&resources[types][]=product

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.

Query parameters

Query parameter Type Description
s (required) String The search query.
resources (required) Hash Requests resources results for the given query, based on the types and limits fields.
types (required) Array Specifies the type of results requested. Currently supports product only.
unavailable_products (optional) String Specifies whether to display unavailable product results. The three possible options are show, hide, and bury. Burying unavailable products pushes them below other matching results. Default: show.
limit (optional) Integer Limits the number of results returned. Default: 10. Min: 1. Max: 10.

Example request_object

{
  "s": "very-fast snowbo",
  "resources": {
    "types": ["product"],
    "limit": 5,
    "unavailable_products": "bury"
  }
}

Example call using jQuery:

jQuery.getJSON("/search/suggest.json", {
  s: "jacket",
  resources: {
    "types": ["product"],
    "limit": 4,
    "unavailable_products": "bury"
  }
}).done(function(response) {
  var productSuggestions = response.resources.results.products;

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

    alert("The title of the first product suggestion is: " + firstProductSuggestion.title);
  }
});

Example call using Fetch:

fetch("/search/suggest.json?s=flannel&resources[types][]=product&resources[limit]=4&resources[unavailable_products]=bury")
.then(response => response.json())
.then(suggestions => {
  const productSuggestions = suggestions.resources.results.products;

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

    alert(`The title of the first product suggestion is: ${
          firstProductSuggestion.title}`
    )
  }
});

Example call using Predictive Search Library

You can find the Predictive Search Library as part of the Shopify/theme-scripts GitHub repository.

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

var predictiveSearch = new PredictiveSearch({
  search_as_you_type: {
    types: [PredictiveSearch.TYPES.PRODUCT],
    limit: 4,
    unavailable_products: "bury"
  }
});


// 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: ${
          firstProductSuggestion.title}`
    )
  }
});


// 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"
      }
    ]
  }
]

Responses

Example response_object:

{
  "resources": {
    "results": {
      "products": ARRAY OF MATCHING product_object
    }
  }
}

Example product_object:

{

  "available": BOOLEAN,
  "body": STRING w/HTML,
  "compare_at_price_max": DECIMAL ("0.00" when the product has no variants with a "compare_at_price"),
  "compare_at_price_min": DECIMAL ("0.00" when the product has no variants with a "compare_at_price"),
  "handle": STRING,
  "id": INTEGER,
  "image": STRING e.g, "https://cdn.shopify.com/s/...",
  "price": DECIMAL,
  "price_max": DECIMAL,
  "price_min": DECIMAL,
  "tags" : ARRAY OF STRING,
  "title": STRING,
  "type" : STRING,
  "url": STRING e.g, "/products/fast-snowboard?_pos=1&_psq=snowb&_ss=e&_v=1.0",
  "variants": [
   {
    "available": BOOLEAN,
    "compare_at_price": DECIMAL (nullable),
    "id": INTEGER,
    "image": STRING e.g, "https://cdn.shopify.com/s/...",
    "price": DECIMAL,
    "title": STRING,
    "url": STRING e.g, "/products/fast-snowboard?_pos=1&_psq=snowb&_ss=e&_v=1.0"
   }
  ],
 "vendor": STRING
}

Error responses

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.

{
  "status": "422",
  "message": "Invalid parameter error",
  "description": "Invalid option for `unavailable_products` parameter"
}

If your theme isn't using one of the supported languages listed above, then the API returns the following error:

{
  "status": "417",
  "message": "Expectation Failed",
  "description": "Unsupported shop primary locale"
}

Exceeding the request throttle limit will return a 429 status code with a relevant error message.

{
  "status": "429",
  "message": "Too many requests",
  "description": "Throttled"
}

In this case, the response will also contain an HTTP header with the Retry-After value in seconds.

Retry-After: 1

All other unexpected errors will return a 5xx status code.

Ready to start selling with Shopify?

Try it free