Add custom plugins to Autocomplete

Autocomplete, InstantSearch, and Recommend in the Algolia app blocks now support version 5 of the Algolia API client. Most stores only need to switch the search client version setting to Version 5. If you use custom storefront JavaScript, follow the version 5 upgrade guide. Support for version 4 ends on August 14, 2026.

Example of sale items

This example shows how to display on-sale products in a separate list (in addition to all other results).

You can achieve this by creating a source that searches into your product index, and applies a filter to only include items where the named_tags.onSale attribute is true.

JavaScript

document.addEventListener("algolia.hooks.initialize", function () {
  // Add the custom plugin to the Autocomplete.
  algoliaShopify.hooks.registerHook(
    "beforeAutocompleteOptions",
    function (options) {
      const { searchClient } = window.algoliaShopify;
      const { getAlgoliaResults } = window.algoliaShopify.externals;

      const saleItemsPlugin = {
        name: "custom-sale-items-plugin",
        getSources({ query }) {
          return [
            {
              sourceId: "saleItems",
              getItems() {
                return getAlgoliaResults({
                  searchClient,
                  queries: [
                    {
                      indexName: "shopify_products",
                      query,
                      params: {
                        filters: "named_tags.onSale:true",
                      },
                    },
                  ],
                });
              },
              templates: {
                header({ html, state }) {
                  return html` <div class="aa-SourceHeader">
                    <span class="aa-SourceHeaderTitle">Sale Items</span>
                    <div class="aa-SourceHeaderLine" />
                  </div>`;
                },
                item({ item, components, html }) {
                  return html`${item.title}`;
                },
              },
            },
          ];
        },
      };
      options.plugins.push(saleItemsPlugin);

      return options;
    },
  );

  // Add the output of the custom plugin to the autocomplete layout.
  algoliaShopify.hooks.registerHook(
    "beforeAutocompleteMainTemplate",
    function (_defaultTemplate, templateOptions, elements, displaySuggestions) {
      const { html } = templateOptions;

      // Add the custom plugin output to the Autocomplete template by referencing
      // the custom plugin sourceId - `saleItems`.
      return html`
        <div class="aa-PanelLayout aa-Panel--scrollable">
          <div class="aa-PanelSections">
            <div class="aa-PanelSection--left">
              ${displaySuggestions &&
              html`
                <div class="aa-SourceHeader">
                  <span class="aa-SourceHeaderTitle"
                    >${window.algoliaShopify.translations.suggestions}</span
                  >
                  <div class="aa-SourceHeaderLine" />
                </div>
                ${elements.querySuggestionsPlugin}
              `}
              ${elements.collections} ${elements.articles} ${elements.pages}
              ${elements.redirectUrlPlugin}
            </div>
            <div class="aa-PanelSection--right">
              ${elements.saleItems} ${elements.products}
            </div>
          </div>
        </div>
      `;
    },
  );
});

​Example of sale items

Example of sale items