Autocomplete custom hooks

Custom hooks that change the behavior of the Autocomplete menu.

beforeAutocompleteAsyncFunction

Use this hook to run asynchronous work (for example, external API requests) before Autocomplete continues.

Parameters

This hook doesn’t accept parameters.

Returns

This hook doesn’t return a value. Return a Promise to delay Autocomplete until your work completes.

Examples

Delay Autocomplete until an async task completes

JavaScript

const sleep = (ms, hookName) =>
	new Promise((resolve) => {
		console.log("sleeping for ", ms, hookName);
		setTimeout(resolve, ms);
	});

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompleteAsyncFunction",
		async () => {
			console.log(
				"----------- beforeAutocompleteAsyncFunction started ----------------",
			);
			await sleep(1000, "beforeAutocompleteAsyncFunction");
		},
	);
});

beforeAutocompleteConfigurationOptions

Modifies the global Autocomplete configuration before any plugin executes a search query. This hook runs on every keystroke and lets you customize search parameters, apply a filter, update analytics tags, or change other search query settings across all Autocomplete sources.

Parameters

config · object

Configuration object.

Show child attributes

searchClient · object

Instance of an Algolia Search API client.

queries · object[]

List of query objects.

Show child attributes

indexName · string

Algolia index name.

query · string

Current search query.

params · object

Search API parameters, such as filters, hitsPerPage, or analyticsTags.

context · object

Context information.

Show child attributes

pluginName · string

Name of the plugin triggering the query, such as products, collections, articles, or pages.

sourceId · string

Unique identifier for the Autocomplete source.

Returns

config · object

Modified configuration object.

Examples

Add analytics tags to product queries

This example adds the tags autocomplete, products, and v2 to the search query for products only.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompleteConfigurationOptions",
		(config, context) => {
			if (context.sourceId === "products") {
				config.queries = config.queries.map((query) => ({
					...query,
					params: {
						...query.params,
						analyticsTags: ["autocomplete", "products", "v2"],
					},
				}));
			}
			return config;
		},
	);
});

Add dynamic filters based on query

This example adds the filter tags:sale to the search, if the query includes the word sale.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompleteConfigurationOptions",
		(config, context) => {
			if (
				context.pluginName === "products" &&
				config.queries[0].query.includes("sale")
			) {
				config.queries = config.queries.map((query) => ({
					...query,
					params: {
						...query.params,
						filters: "tags:sale",
					},
				}));
			}
			return config;
		},
	);
});

beforeAutocompletePluginOptions

Customizes individual plugin options during plugin construction. This hook runs once per plugin at initialization time. Use the hook to set static defaults like base filters, analytics tags, or custom transform functions.

Parameters

options · object

Plugin options.

Show child attributes

searchParameters · object

Search parameters for this plugin.

sourceId · string

Unique identifier for the Autocomplete source.

transformItems · function

Function for transforming items before they’re rendered.

analyticsTags · string[]

Analytics tags.

context · object

Context information.

Show child attributes

pluginName · string

Name of the plugin, such as products, collections, articles, or pages.

sourceId · string

Unique identifier for the Autocomplete source.

Returns

options · object

Modified plugin options.

Examples

Set base filters per plugin

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompletePluginOptions",
		(options, context) => {
			if (context.pluginName === "products") {
				options.searchParameters.filters = "inventory_quantity > 0";
			} else if (context.pluginName === "collections") {
				options.searchParameters.filters = "published:true";
			}
			return options;
		},
	);
});

Customize hits per page per plugin

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompletePluginOptions",
		(options, context) => {
			if (context.pluginName === "products") {
				options.searchParameters.hitsPerPage = 12;
			} else if (context.pluginName === "articles") {
				options.searchParameters.hitsPerPage = 5;
			}
			return options;
		},
	);
});

beforeAutocompletePluginsArray

Manages the plugin array before creating the Autocomplete instance. This hook runs once at initialization and lets you add and remove plugins, or reorder the plugin array.

To work with plugins, use the arguments object to extract them into an array.

Parameters

...plugins · any[]

List of plugins passed to the Autocomplete instance.

Returns

plugins · any[]

Modified plugin list.

Examples

Remove articles and pages plugins

This example removes the articles and pages plugins.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompletePluginsArray",
		function () {
			// Extract plugins from arguments
			var plugins = Array.prototype.slice.call(arguments);

			// Remove articles and pages plugins
			return plugins.filter((plugin) => {
				if (!plugin || !plugin.getSources) return true;

				var sources = plugin.getSources({ query: "" });
				if (!sources || !sources.length) return true;

				// Remove plugins that expose articles or pages
				return !sources.some(
					(source) =>
						source.sourceId === "articles" || source.sourceId === "pages",
				);
			});
		},
	);
});

beforeAutocompleteOptions

Use this hook to set or change Autocomplete options, such as the placeholder text.

Parameters

options · object

Autocomplete options.

Returns

options · object

Modified Autocomplete options.

Examples

Change the placeholder text

This example changes the placeholder text.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook("beforeAutocompleteOptions", (options) => {
		// Change the placeholder text of the Autocomplete menu
		options.placeholder = "Search our products";
		return options;
	});
});

beforeAutocompleteFiltersString

Use this hook to add or override filters in the Autocomplete menu.

Parameters

filters · string

Filters.

Returns

filters · string

Modified filters.

Examples

Return a custom filter

This example returns a custom filter instead of the default.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompleteFiltersString",
		(_defaultFilter) => {
			// Return a custom filter instead of the default filter.
			return "price > 17";
		},
	);
});

beforeAutocompleteRedirectUrlOptions

Changes the default parameters of the createRedirectUrlPlugin function.

Parameters

options · object

Redirect URL plugin options.

Returns

options · object

Modified Redirect URL plugin options.

Examples

Add a custom class to redirect links

This example changes the template for the redirect link by adding a custom CSS class.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompleteRedirectUrlOptions",
		(options) => {
			// Change the default template for rendering redirect items
			return {
				templates: {
					item({ html, state }) {
						return html`<a className="myCustomClass">${state.query}</a>`;
					},
				},
			};
		},
	);
});

beforeAutocompleteMainTemplate

Changes the HTML template that renders the Autocomplete panel. Use this to render an Autocomplete multi-panel layout.

Parameters

_defaultTemplate

Default template.

templateOptions · object

Template options including the html tagged template function.

elements · object

Template elements.

Show child attributes

querySuggestionsPlugin

Query suggestions panel element.

collections

Collections panel element.

articles

Articles panel element.

pages

Pages panel element.

redirectUrlPlugin

Redirect URL panel element.

products

Products panel element.

displaySuggestions · boolean

Whether to render query suggestions.

Returns

template

Template to render.

Examples

Render a two-column layout

This example returns a custom two-column layout as template.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompleteMainTemplate",
		(_defaultTemplate, templateOptions, elements, displaySuggestions) => {
			const { html } = templateOptions;
			// Don't return the default template and return a custom two-column layout instead
			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"
                    >${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.products}
          </div>
        </div>
      </div>
    `;
		},
	);
});

beforeAutocompleteMainProductsTemplate

Renders the product section in the Autocomplete menu.

Parameters

_defaultTemplate

Default template.

templateOptions

Template options including the html tagged template function.

elements · object

Contains the products element.

Show child attributes

products

Products section element.

Returns

template

Template to render.

Examples

Render the products section

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompleteMainProductsTemplate",
		(_defaultTemplate, templateOptions, elements) => {
			const { html } = templateOptions;
			return html`
      <div class="aa-PanelLayout aa-Panel--scrollable">
        <div class="aa-PanelSection">
          ${elements.products}
        </div>
      </div>
    `;
		},
	);
});

beforeAutocompleteNoResultsTemplate

Renders a template when Autocomplete doesn’t return results.

Parameters

_defaultTemplate

Default template.

templateOptions

Template options including the html and state properties.

Returns

template

Template to render.

Examples

Customize the no results panel

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompleteNoResultsTemplate",
		(_defaultTemplate, templateOptions) => {
			const { html, state } = templateOptions;
			return html`
      <div class="aa-PanelLayout aa-Panel--scrollable">
        <p class="aa-NoResultsHeader">
          ${algoliaShopify.translation_helpers.no_result_for(state.query)}
        </p>
        <a class="aa-NoResultsLink" href="${window.Shopify.routes.root}search?q=">
          ${algoliaShopify.translations.allProducts}
        </a>
      </div>
    `;
		},
	);
});

beforeAutocompleteHeaderTemplate

Renders a header section at the top of the Autocomplete results panel.

Parameters

_defaultTemplate

Default template.

templateOptions

Template options including the html and state properties.

resource · string

Resource type.

Returns

template

Template to render.

Examples

Customize the results header

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompleteHeaderTemplate",
		(_defaultTemplate, templateOptions, resource) => {
			const { html, state } = templateOptions;
			return html`
      <div class="aa-SourceHeader">
        <span class="aa-SourceHeaderTitle">
          ${algoliaShopify.translation_helpers.render_title(
						resource,
						state.query,
					)}
        </span>
        <div class="aa-SourceHeaderLine" />
      </div>
    `;
		},
	);
});

beforeAutocompleteFooterTemplate

Renders a footer section at the bottom of the Autocomplete results panel. To render a footer, select the Show See All products option in the Autocomplete search options in your store’s admin.

Parameters

_defaultTemplate

Default template.

templateOptions

Template options including the html and state properties.

Returns

template

Template to render.

Examples

Render a footer with a “See all products” link

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompleteFooterTemplate",
		(_defaultTemplate, templateOptions) => {
			const { html, state } = templateOptions;
			return html`
      <div class="aa-footer">
        <a
          class="aa-SeeAllBtn"
          href="${window.Shopify.routes.root}search?q=${state.query}"
        >
          ${algoliaShopify.translations.allProducts}
          (${algoliaShopify.helpers.formatNumber(state.context.nbProducts)})
        </a>
      </div>
    `;
		},
	);
});

beforeAutocompleteProductTemplate

Template for rendering each product hit in the Autocomplete results.

If you are using this template, ensure you also call trackSearchAttribution(item) to properly handle events.

Parameters

_defaultTemplate

Default template.

templateOptions

Template options including html, item, and components.

distinct · boolean

Whether distinct mode is enabled.

itemLink · string

Product URL.

trackSearchAttribution

Function to track search attribution.

Returns

template

Template to render.

Examples

Customize product items

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompleteProductTemplate",
		(
			_defaultTemplate,
			templateOptions,
			distinct,
			itemLink,
			trackSearchAttribution,
		) => {
			// Modify default options, then return them
			const { html, item, components } = templateOptions;
			return html`
    <a
      href="${itemLink}"
      class="aa-ItemLink aa-ProductItem"
      onClick="${() => trackSearchAttribution(item)}"
    >
      <div class="aa-ItemContent">
        <div class="aa-ItemPicture aa-ItemPicture--loaded">
          <img
            src="${algoliaShopify.helpers.renderImage(item, 125).src}"
            srcset="${algoliaShopify.helpers.renderImage(item, 125).srcset}"
            sizes="${algoliaShopify.helpers.renderImage(item, 125).sizes}"
            alt="${item.title}"
          />
        </div>
        <div class="aa-ItemContentBody">
          <div class="aa-ItemContentBrand">
            ${
							item.product_type &&
							components.Highlight({ hit: item, attribute: "product_type" })
						}
           removing vendor
          </div>
          <div class="aa-ItemContentTitleWrapper">
            <div class="aa-ItemContentTitle">
              ${components.Highlight({ hit: item, attribute: "title" })}
              <span class="algolia-variant">
                ${algoliaShopify.helpers.variantTitleAddition(item, distinct)}
              </span>
            </div>
          </div>
          <div class="aa-ItemContentPrice">
            <div class="aa-ItemContentPriceCurrent">
              ${algoliaShopify.helpers.displayPrice(item, distinct)}
            </div>
          </div>
        </div>
      </div>
    </a>
  `;
		},
	);
});

beforeAutocompleteArticlesTemplate

Template for rendering each article hit in the Autocomplete results.

Parameters

_defaultTemplate

Default template.

templateOptions

Template options including html, item, and components.

itemLink · string

Article URL.

Returns

template

Template to render.

Examples

Customize article items

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompleteArticlesTemplate",
		(_defaultTemplate, templateOptions, itemLink) => {
			const { item, html, components } = templateOptions;
			return html`
    <a href="${itemLink}" class="aa-ItemLink">
      <div class="aa-ItemWrapper">
        <div class="aa-ItemContent">
          <div class="aa-ItemIcon aa-ItemIcon--noBorder">
            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
              <path
                stroke-linecap="round"
                stroke-linejoin="round"
                stroke-width="2"
                d="M7 7h.01M7 3h5c.512 0 1.024.195 1.414.586l7 7a2 2 0 010 2.828l-7 7a2 2 0 01-2.828 0l-7-7A1.994 1.994 0 013 12V7a4 4 0 014-4z"
              />
            </svg>
          </div>
          <div class="aa-ItemContentBody">
            <div class="aa-ItemContentTitle">
              ${components.Highlight({ hit: item, attribute: "title" })}
            </div>
          </div>
        </div>
      </div>
    </a>
  `;
		},
	);
});

beforeAutocompleteCollectionsTemplate

Template for rendering each collection hit in the Autocomplete results.

Parameters

_defaultTemplate

Default template.

templateOptions

Template options including html, item, and components.

itemLink · string

Collection URL.

Returns

template

Template to render.

Examples

Customize collection items

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompleteCollectionsTemplate",
		(_defaultTemplate, templateOptions, itemLink) => {
			const { html, item, components } = templateOptions;
			return html`
      <a href="${itemLink}" class="aa-ItemLink">
        <div class="aa-ItemWrapper">
          <div class="aa-ItemContent">
            <div class="aa-ItemIcon aa-ItemIcon--noBorder">
              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
                <path
                  stroke-linecap="round"
                  stroke-linejoin="round"
                  stroke-width="2"
                  d="M4 6a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2H6a2 2 0 01-2-2V6zM14 6a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2h-2a2 2 0 01-2-2V6zM4 16a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2H6a2 2 0 01-2-2v-2zM14 16a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2h-2a2 2 0 01-2-2v-2z"
                />
              </svg>
            </div>
            <div class="aa-ItemContentBody">
              <div class="aa-ItemContentTitle">
                ${components.Highlight({ hit: item, attribute: "title" })}
              </div>
            </div>
          </div>
        </div>
      </a>
    `;
		},
	);
});

beforeAutocompletePagesTemplate

Template for rendering each pages hit in the Autocomplete results.

Parameters

_defaultTemplate

Default template.

templateOptions

Template options including html, item, and components.

itemLink · string

Page URL.

Returns

template

Template to render.

Examples

Customize page items

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompletePagesTemplate",
		(_defaultTemplate, templateOptions, itemLink) => {
			const { html, item, components } = templateOptions;
			return html`
      <a href="${itemLink}" class="aa-ItemLink aa-ProductItem">
        <div class="aa-ItemWrapper">
          <div class="aa-ItemContent">
            <div class="aa-ItemIcon aa-ItemIcon--noBorder">
              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
                <path
                  stroke-linecap="round"
                  stroke-linejoin="round"
                  stroke-width="2"
                  d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
                />
              </svg>
            </div>
            <div class="aa-ItemContentBody">
              <div class="aa-ItemContentTitle">
                ${components.Highlight({ hit: item, attribute: "title" })}
              </div>
            </div>
          </div>
        </div>
      </a>
    `;
		},
	);
});

beforeAutocompleteSuggestionsTemplate

Template for rendering each search suggestion in the Autocomplete menu.

Parameters

_defaultTemplate

Default template.

templateOptions

Template options including html, item, and components.

Returns

template

Template to render.

Examples

Customize suggestions

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompleteSuggestionsTemplate",
		(_defaultTemplate, templateOptions) => {
			const { html, item, components } = templateOptions;
			return html`
      <a
        class="aa-ItemLink aa-ItemWrapper"
        href="${window.Shopify.routes.root}search?q=${item.query}"
      >
        <div class="aa-ItemContent">
          <div class="aa-ItemIcon aa-ItemIcon--noBorder">
            <svg viewBox="0 0 24 24" fill="currentColor">
              <path d="M16.041 15.856c-0.034 0.026-0.067 0.055-0.099 0.087s-0.060 0.064-0.087 0.099c-1.258 1.213-2.969 1.958-4.855 1.958-1.933 0-3.682-0.782-4.95-2.050s-2.050-3.017-2.050-4.95 0.782-3.682 2.050-4.95 3.017-2.050 4.95-2.050 3.682 0.782 4.95 2.050 2.050 3.017 2.050 4.95c0 1.886-0.745 3.597-1.959 4.856zM21.707 20.293l-3.675-3.675c1.231-1.54 1.968-3.493 1.968-5.618 0-2.485-1.008-4.736-2.636-6.364s-3.879-2.636-6.364-2.636-4.736 1.008-6.364 2.636-2.636 3.879-2.636 6.364 1.008 4.736 2.636 6.364 3.879 2.636 6.364 2.636c2.125 0 4.078-0.737 5.618-1.968l3.675 3.675c0.391 0.391 1.024 0.391 1.414 0s0.391-1.024 0-1.414z" />
            </svg>
          </div>
          <div class="aa-ItemContentBody">
            <div class="aa-ItemContentTitle">
              ${components.Highlight({ hit: item, attribute: "query" })}
            </div>
          </div>
        </div>
        <div class="aa-ItemActions">
           <button
             class="aa-ItemActionButton"
             title="Fill query with ${item.query}"
           >
             <svg viewBox="0 0 24 24" fill="currentColor">
               <path d="M8 17v-7.586l8.293 8.293c0.391 0.391 1.024 0.391 1.414 0s0.391-1.024 0-1.414l-8.293-8.293h7.586c0.552 0 1-0.448 1-1s-0.448-1-1-1h-10c-0.552 0-1 0.448-1 1v10c0 0.552 0.448 1 1 1s1-0.448 1-1z" />
             </svg>
           </button>
        </div>
      </a>
    `;
		},
	);
});

beforeAutocompleteProductTransformResponseHits

Modifies the hits before rendering them in the Autocomplete menu. For more information, see transformResponse.

Parameters

hits · array

Search results.

results · object

Full results from Algolia.

Returns

hits · array

Modified search results.

Examples

Transform product hits before rendering

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompleteProductTransformResponseHits",
		(hits, results) => {
			console.log(hits);
			return hits;
		},
	);
});

afterAutocompleteProductClickAction (deprecated)

This hook is deprecated. Use beforeAutocompleteProductTemplate instead.

Adds a click handler function to the product template. Call this hook after a user clicks a product.

Parameters

_ · any

First parameter (unused).

line_item · object

Product line item that was clicked.

See also

• Add custom hooks
• Insights and Recommend hooks
• InstantSearch hooks