Shopify AJAX Predictive Search API

Usage no npm install needed!

<script type="module">
  import shopifyThemePredictiveSearch from 'https://cdn.skypack.dev/@shopify/theme-predictive-search';


Shopify Predictive Search JS API

Configuration options

Options Type Description
search_path (optional) String Search path to prepend the predictive search route in different locales (e.g. /fr/search). Default to /search
resources (required) Object Requests resources results for the given query, based on the type and limit fields.
type (required) Array Specifies the type of results requested. Valid values: product, page, article, collection.
limit (optional) Integer Limits the number of results returned. Default: 10. Min: 1. Max: 10.
options (optional) Object Specifies options for the requested resources based on the unavailable_products and fields settings.
unavailable_products (optional) String Specifies whether to display results for unavailable products. The three possible options are show, hide, and last. Set to last to display unavailable products below other matching results. Set to hide to filter out unavailable products from the search results. Default: last.
fields (optional) Array Specifies the list of fields to search on. Valid fields are: author, body, product_type, tag, title, variants.barcode, variants.sku, variants.title, and vendor. The default fields searched on are: title, product_type, variants.title, and vendor. For the best search experience, we recommend searching on the default field set or as few fields as possible.

See the help docs for Predictive Search for more information.

Getting started

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

var predictiveSearch = new PredictiveSearch({
  search_path: PredictiveSearch.SEARCH_PATH,
  resources: {
    type: [PredictiveSearch.TYPES.PRODUCT],
    limit: 4,
    options: {
      unavailable_products: "last",
      fields: [

predictiveSearch.on("success", function(json) {
  // See "Success Response" section of this document

predictiveSearch.on("error", function(error) {
  // See "HTTP status `3xx-4xx` Response" section of this document

predictiveSearch.query("Yeti SB165");

Success Response

// JSON Output
  "resources": {
    "results": {
      "products": [
          "available": true,
          "body": "<p>The best bike ever made</p>",
          "compare_at_price_max": "5199.99",
          "compare_at_price_min": "4899.99",
          "handle": "yeti-sb165",
          "id": 111,
          "image": "https://cdn.shopify.com/s/...",
          "price": "4999.99",
          "price_max": "5199.99",
          "price_min": "4899.99",
          "tags": ["best", "bike", "ever", "made"],
          "title": "Yeti SB165",
          "type": "best-bike",
          "url": "/products/sb165",
          "variants": [
              "available": true,
              "compare_at_price": "9999.99",
              "id": 222,
              "image": "https://cdn.shopify.com/s/...",
              "price": "9999.99",
              "title": "Yeti SB165 X01 build",
              "url": "/products/sb165/x01"
          "vendor": "Yeti Cyclesr"

HTTP status 3xx-4xx Response

predictiveSearch.on("error", function(error) {
  console.error(error.status); // Ex. output: 429
  console.error(error.name); // Ex. output: Throttled
  console.error(error.message); // Ex. output: Too Many Requests

  // When the request response HTTP status is 429
  console.error(error.retryAfter); // Ex. output: 100