InstantSearch custom hooks

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.

`beforeInstantSearchAsyncFunction`

Use this hook to run asynchronous work (for example, an external API request) before InstantSearch sets any parameters. Add several await statements to run tasks in sequence.

Parameters

This hook doesn’t accept parameters.

Returns

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

Examples

Delay InstantSearch until an async task completes

Return a Promise to pause InstantSearch while you run async work.

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(
		"beforeInstantSearchAsyncFunction",
		async () => {
			console.log(
				"----------- beforeInstantSearchAsyncFunction started ----------------",
			);
			await sleep(1000, "beforeInstantSearchAsyncFunction");
		},
	);
});

`beforeInstantSearchConfigurationOptions`

Changes InstantSearch options.

Parameters

object

InstantSearch configuration options.

Returns

object

Modified configuration options.

Examples

Customize InstantSearch configuration options

Update InstantSearch options before it initializes.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeInstantSearchConfigurationOptions",
		(options) => {
			// Modify default options, then return them
			options.numberLocale = "fr";
			options.stalledSearchDelay = 500;

			return options;
		},
	);
});

`beforeInstantSearchOptions`

Changes the following parameters:

Parameters

object

InstantSearch options with the following properties:

colors
distinct
facets
hitsPerPage
selector
sortOrders
swatchRowLimit

Returns

object

Modified InstantSearch options.

Examples

Show fewer swatch chips in the row

swatchRowLimit sets how many swatch chips a product-level card shows in its row. The rest go behind the +N button that opens the overflow panel. Set it to 0 to remove the cap, so the row holds every option and no panel renders.Every option stays on the card either way. To remove options altogether, use beforeInstantSearchSwatchOptionResolver.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook("beforeInstantSearchOptions", (options) => {
		// A product with 10 options shows 6 chips and a "+4" button
		options.swatchRowLimit = 6;

		return options;
	});
});

`beforeInstantSearchAllowParamsArray`

Preserves URL parameters when navigating through the search results.

Parameters

string[]

URL parameter names to preserve.

Returns

string[]

Modified parameter names.

Examples

Preserve a custom URL parameter

Add ref to the allowlist so InstantSearch preserves it in the URL.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeInstantSearchAllowParamsArray",
		function () {
			// Add a new search parameter
			const allowParamsArray = [...arguments, "ref"];
			return allowParamsArray;
		},
	);
});

`beforeInstantSearchFiltersString`

Changes the filter parameter of the search results page.

Parameters

string

Default (may be empty).

Returns

string

Filters to apply.

Examples

Add a filter condition

Append a price filter to the existing filter string, if present.

JavaScript

// Modify default `defaultFilter` if it exists
document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeInstantSearchFiltersString",
		(defaultFilter) => {
			// Modify or replace the default string, then return a string
			if (defaultFilter) {
				return defaultFilter + " AND price > 5";
			} else {
				return "price > 5";
			}
		},
	);
});

`beforeInstantSearchRuleContexts`

Modifies the ruleContexts sent with InstantSearch queries. Use this hook to trigger Rules based on page context, such as UTM parameters, customer segments, or custom page metadata. On collection pages, the default contexts include the collection handle and shopify_default_collection.

Parameters

string[]

Default rule contexts. On collection pages, this includes the collection handle and shopify_default_collection. On other pages, this is an empty array.

Returns

string[]

Modified rule contexts. Duplicates are removed and the list is limited to 10 items.

Examples

Add rule contexts based on UTM parameters

This example adds a rule context based on the utm_source URL parameter.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeInstantSearchRuleContexts", (...rules) => {
			var params = new URLSearchParams(window.location.search);
			var utmSource = params.get("utm_source");
			if (utmSource) {
				rules.push("campaign-" + utmSource);
			}
			return rules;
		},
	);
});

`beforeInstantSearchMainTemplate`

Template for the main template container. If you’re using the facet display feature, include a div with class="ais-facets-container" to display the facets.

Parameters

Default template.

object

Contains facets and configuration.

Tagged template function for rendering HTML.

Returns

Template to render.

Examples

Customize the main template

Return a custom page layout that includes facet, stats, and results containers.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeInstantSearchMainTemplate",
		(_defaultTemplate, data, html) => html`
      <div class="ais-page">
        <h1 class="ais-h2">${algoliaShopify.translations.searchTitle}</h1>
        <div class="ais-input">
          <div class="ais-search-box-container"></div>
          <div class="ais-input-button">
            <div class="ais-clear-input-icon"></div>
          </div>
        </div>
        <div class="ais-facets-button">
          ${algoliaShopify.translations.showFilters}
        </div>
        <div class="ais-facets">
          <div class="ais-clear-refinements-container"></div>
          <div class="ais-current-refined-values-container"></div>
          ${
						algoliaShopify.config.app_blocks_dynamic_widgets_beta_enabled
							? html`
                <div class="ais-dynamic-widgets-container"></div>
              `
							: data.facets.map(
									(facet) =>
										html`
                    <div
                      class="ais-facet-dropdown-wrapper ais-facet-${facet.type} ais-facet-${facet.escapedName}"
                    >
                      <label
                        for="${facet.escapedName}"
                        class="ais-range-slider--header ais-facet--header ais-header"
                        >${facet.title}</label
                      >
                      <input
                        class="ais-dropdown-checkbox"
                        type="checkbox"
                        id="${facet.escapedName}"
                        name="dropdown"
                      />
                      <div
                        class="ais-facet-${facet.escapedName}-container ais-facet-dropdown-container"
                      ></div>
                    </div>
                  `,
								)
					}
        </div>
        <div class="ais-block">
          <div class="ais-search-header">
            <div class="ais-stats-container"></div>
            <div class="ais-change-display">
              <span class="ais-change-display-block ais-change-display-selected"
                ><i class="fa fa-th-large"></i
              ></span>
              <span class="ais-change-display-list"
                ><i class="fa fa-th-list"></i
              ></span>
            </div>
            <div class="ais-sort">
              ${
								data.multipleSortOrders
									? html`
                    ${algoliaShopify.translations.sortBy}
                    <span class="ais-sort-orders-container"></span>
                  `
									: html`
                    ${algoliaShopify.translations.sortBy}
                    ${algoliaShopify.translations.relevance}
                  `
							}
            </div>
          </div>
          <div class="ais-hits-container ais-results-as-block"></div>
        </div>
        <div class="ais-pagination-container"></div>
      </div>
    `,
	);
});

`beforeInstantSearchProductTemplate`

Template for product hits in the search results. When using this template, also call trackSearchAttribution(hit) to properly handle events.

Parameters

Default template.

object

Product hit. On a product-level record, hit._productLevel is true and the variants are nested under hit.variants. The chips to render are on hit._swatchOptions, each one shaped like the options the swatch resolver returns, with _matched on the chip the app preselected. See Product cards.

Tagged template function for rendering HTML.

object

InstantSearch components (like Highlight).

Function to track search attribution. Equivalent to algoliaShopify.helpers.handleItemClick.

Returns

Template to render.

Examples

Customize product hits

Return a custom product-hit template and call trackSearchAttribution(hit) to track events.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeInstantSearchProductTemplate",
		(_defaultTemplate, hit, html, components, trackSearchAttribution) => html`
      <div
        class="ais-hit ais-product"
        data-algolia-index="${hit.index}"
        data-algolia-position="${hit.productPosition}"
        data-algolia-queryid="${hit.queryID}"
        data-algolia-objectid="${hit.objectID}"
        data-handle="${hit.handle}"
        data-variant-id="${hit.objectID}"
        data-distinct="${hit._distinct}"
        data-product-id="${hit.id}"
        onClick="${() => trackSearchAttribution(hit)}"
      >
        <img
          class="ais-hit--picture"
          src="${algoliaShopify.helpers.mediumImage(hit)}"
          alt="${hit.title} - ${hit.variant_title}"
        />

        <div class="ais-hit--details">
          <p class="ais-hit--title">
            <a
              data-algolia-index="${hit.index}"
              data-algolia-position="${hit.productPosition}"
              data-algolia-queryid="${hit.queryID}"
              data-algolia-objectid="${hit.objectID}"
              href="${algoliaShopify.helpers.instantsearchLink(hit)}"
              title="${algoliaShopify.helpers.fullTitle(
								hit.title,
								hit._distinct,
								hit.variant_title,
							)}"
            >
              ${components.Highlight({ attribute: "title", hit })}
              ${algoliaShopify.helpers.variantTitleAddition(hit, hit._distinct)}
            </a>
          </p>
          <p
            class="ais-hit--subtitle"
            title="${hit.product_type}${algoliaShopify.translation_helpers.by(
							hit.vendor,
						)}"
          >
            ${components.Highlight({ attribute: "product_type", hit })}
            ${
							hit.vendor &&
							html`
                <span> ${algoliaShopify.translations.by} </span>
              `
						}
            ${hit.vendor && components.Highlight({ attribute: "vendor", hit })}
          </p>
          <p class="ais-hit--price">
            <b>${algoliaShopify.helpers.displayPrice(hit, hit._distinct)}</b>
            ${
							!hit._distinct &&
							html`
                <span class="ais-hit--price-striked"
                  ><span
                    >${algoliaShopify.helpers.displayStrikedPrice(
											hit.price,
											hit.compare_at_price,
										)}</span
                  ></span
                >
              `
						}
            ${
							!hit._distinct &&
							html`
                <span class="ais-hit--price-discount"
                  >${algoliaShopify.helpers.displayDiscount(
										hit.price,
										hit.compare_at_price,
										hit.price_ratio,
									)}</span
                >
              `
						}
          </p>
          <!-- Extra info examples - Remove the display: none to show them -->
          <p class="ais-hit--info" style="display: none">
            ${
							hit.sku &&
							html`
                <span class="algolia-sku"
                  >${components.Highlight({ attribute: "sku", hit })}</span
                >
              `
						}
            ${
							hit.barcode &&
							html`
                <span class="algolia-barcode"
                  >${components.Highlight({ attribute: "barcode", hit })}</span
                >
              `
						}
            ${
							hit.weight &&
							html`
                <span class="algolia-weight">${hit.weight}</span>
              `
						}
            ${
							!hit.taxable &&
							html`
                <span class="algolia-taxable"
                  >${algoliaShopify.translations.taxFree}</span
                >
              `
						}
          </p>
          <!-- Tags example - Remove the display: none to show them -->
          <p class="ais-hit--tags" style="display: none">
            ${hit?._highlightResult.tags?.map(
							(tag) =>
								html`
                  <span class="ais-hit--tag">${tag.value}</span>
                `,
						)}
          </p>
          ${
						!hit._distinct &&
						html`
              <form
                id="algolia-add-to-cart-${hit.objectID}"
                style="display: none;"
                action="/cart/add"
                method="post"
                enctype="multipart/form-data"
              >
                <input type="hidden" name="id" value="${hit.objectID}" />
              </form>
              <p class="ais-hit--cart">
                ${
									hit.can_order
										? html`
                      <button
                        class="ais-hit--cart-button"
                        data-form-id="algolia-add-to-cart-${hit.objectID}"
                      >
                        ${algoliaShopify.translations.addToCart}
                      </button>
                    `
										: html`
                      <button
                        class="ais-hit--cart-button ais-hit--cart-button__disabled"
                      >
                        ${algoliaShopify.translations.outOfStock}
                      </button>
                    `
								}
              </p>
            `
					}
        </div>
      </div>
    `,
	);
});

Customize product-level hits

Product-level hits carry variants[], so the card shows a swatch row and a price range instead of a single variant’s price and an add-to-cart button. Check hit._productLevel and keep your variant-level template for the other branch.Keep the class names and data- attributes from this example. The app delegates chip clicks from the results container and reads them to retarget the card image, the title link, and the overflow panel.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeInstantSearchProductTemplate",
		(_defaultTemplate, hit, html, components, trackSearchAttribution) => {
			if (!hit._productLevel) {
				return _defaultTemplate;
			}

			const swatchOptions = hit._swatchOptions || [];
			const matchedSwatch = swatchOptions.find((option) => option._matched);
			const rowLimit =
				algoliaShopify.instantsearch.swatchRowLimit || swatchOptions.length;
			const rowSwatches = swatchOptions.slice(0, rowLimit);
			const panelSwatches = swatchOptions.slice(rowLimit);

			const productHref = algoliaShopify.helpers.instantsearchLink(hit);
			const titleHref = matchedSwatch?.variantID
				? `${productHref}?variant=${matchedSwatch.variantID}`
				: productHref;

			const swatchChip = (option) => html`
        <button
          type="button"
          class="ais-hit--swatch ${option._matched
						? "ais-hit--swatch__selected"
						: ""} ${option.available ? "" : "ais-hit--swatch__oos"}"
          title="${option.name}"
          aria-label="${option.name}"
          aria-pressed="${option._matched ? "true" : "false"}"
          data-swatch-name="${option.name}"
          data-product-image="${option.productImage || ""}"
          data-variant-id="${option.variantID || ""}"
          style="${option.swatchImage
						? `background-image:url(${option.swatchImage})`
						: `background-color:${option.color}`}"
        ></button>
      `;

			return html`
        <div
          class="ais-hit ais-product ais-hit--product-level"
          data-algolia-index="${hit.index}"
          data-algolia-position="${hit.productPosition}"
          data-algolia-queryid="${hit.queryID}"
          data-algolia-objectid="${hit.objectID}"
          data-handle="${hit.handle}"
          data-variant-id="${matchedSwatch?.variantID || ""}"
          onClick="${() => trackSearchAttribution(hit)}"
        >
          <img
            class="ais-hit--picture"
            src="${algoliaShopify.helpers.renderImage(hit, 250).src}"
            alt="${hit.title}"
          />

          <div class="ais-hit--details">
            ${rowSwatches.length > 0 &&
						html`
              <div class="ais-hit--swatches-bar">
                <div class="ais-hit--swatches">
                  ${rowSwatches.map(swatchChip)}
                </div>
                ${panelSwatches.length > 0 &&
								html`
                  <button
                    type="button"
                    class="ais-hit--swatches-more"
                    aria-expanded="false"
                  >
                    +${panelSwatches.length}
                  </button>
                `}
              </div>
              ${panelSwatches.length > 0 &&
							html`
                <div class="ais-hit--swatches-panel">
                  ${panelSwatches.map(swatchChip)}
                </div>
              `}
            `}
            <p class="ais-hit--title">
              <a href="${titleHref}">
                ${components.Highlight({ attribute: "title", hit })}
              </a>
            </p>
            <p class="ais-hit--price">
              <b
                >${algoliaShopify.helpers.displayPrice(
									hit,
									hit._distinct,
									hit._productLevel,
								)}</b
              >
            </p>
          </div>
        </div>
      `;
		},
	);
});

`beforeInstantSearchNoResultTemplate`

Template for when there are no results.

Parameters

Default template.

Tagged template function for rendering HTML.

Returns

Template to render.

Examples

Customize the no results template

Replace the default empty state with a custom template.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeInstantSearchNoResultTemplate",
		(_defaultTemplate, html) => html`
      <div class="ais-hit-empty">
        <div class="ais-hit-empty--title">
          ${algoliaShopify.translations.noResultFound}
        </div>
        <div class="ais-hit-empty--clears">
          ${algoliaShopify.translations.try} ${" "}
          <a class="ais-hit-empty--clear-filters ais-link">
            ${algoliaShopify.translations.clearFilters} ${" "}
          </a>
          ${algoliaShopify.translations.or} ${" "}
          <a class="ais-hit-empty--clear-input ais-link">
            ${algoliaShopify.translations.changeInput}
          </a>
        </div>
      </div>
    `,
	);
});

`beforeInstantSearchStatsTemplate`

Template for search stats

If the active sort order uses a virtual replica, the response includes nbSortedHits: the number of results Algolia considered were relevant enough to sort. Use nbSortedHits to show a message such as “42 relevant results sorted out of 1,247” instead of only the total hit count.

Parameters

Default template.

object

Contains search statistics, for example nbHits, nbSortedHits, page, and hitsPerPage.

Tagged template function for rendering HTML.

Returns

Template to render.

Examples

Customize the stats template

Customize the stats template for one or many results.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeInstantSearchStatsTemplate",
		(_defaultTemplate, data, html) => html`
      ${
				data.hasOneResult &&
				html`
          <span class="ais-stats--nb-results">
            1 result found
          </span>
        `
			}
      ${
				data.hasManyResults &&
				html`
          ${data.page * data.hitsPerPage + 1} - ${" "}
          ${Math.min((data.page + 1) * data.hitsPerPage, data.nbHits)} ${" "}
          out of
          <span class="ais-stats--nb-results">
            ${" "} ${algoliaShopify.helpers.formatNumber(data.nbHits)} ${" "}
            results found
          </span>
        `
			}
      ${" "} in ${data.processingTimeMS / 1000}s
    `,
	);
});

`beforeInstantSearchTransformItems`

Change items before they’re rendered.

Parameters

array

Search result items.

array

Original items.

Returns

array

Modified items.

Examples

Mark out-of-stock items

Set can_order to false for items with inventory_quantity equal to 0.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeInstantSearchTransformItems",
		(transformedItems, items) => {
			// Mark out-of-stock items
			return transformedItems.map((item) => {
				if (item.inventory_quantity === 0) {
					item.can_order = false;
				}
				return item;
			});
		},
	);
});

`beforeInstantSearchSwatchOptionResolver`

Reorder or filter the swatch chips on a product-level card before the template renders them. Only fires for product-level hits whose records carry swatch data.

An option you drop here is gone from the card, including the overflow panel. To keep every option but show fewer chips in the row, set swatchRowLimit with beforeInstantSearchOptions instead.

Each resolved option arrives as its own argument, followed by the hit, so read the arguments object rather than named parameters. This hook runs before the app picks the preselected chip. An option you remove here can no longer be preselected. To reorder chips without changing which one is preselected, use beforeInstantSearchTransformItems and edit _matched on hit._swatchOptions.

Parameters

object

Each resolved swatch option, spread as a separate argument. An option has name, color, swatchImage, productImage, variantID, and available.

object

Product hit the chips belong to. Arrives as the last argument, after the options.

Returns

array

Swatch options to render.

Examples

Show the first five in-stock swatches

Drop sold-out options, then cap the row at five chips.

JavaScript

document.addEventListener('algolia.hooks.initialize', function() {
  algoliaShopify.hooks.registerHook('beforeInstantSearchSwatchOptionResolver', (...hookArgs) => {
    const swatchOptions = hookArgs.slice(0, -1); // Drop the trailing internal argument

    // Drop sold-out options, then cap the row
    return swatchOptions
      .filter(function(option) {
        return option.available;
      })
      .slice(0, 2);
  });
});

`afterInstantSearchSwatchClick`

Runs after a shopper clicks a swatch chip. The app has already marked the chip, swapped the card image, and re-pointed the card at the selected variant before this hook runs. This hook doesn’t use a return value. The app doesn’t fire this hook for a chip it preselected on first render.

Parameters

object

Details of the click, with the following properties:

swatchButton: element of the chip the shopper clicked.
hitEl: card element that holds the chip.
optionValue: name of the clicked option value.

Examples

Track swatch clicks

Send the clicked option value and the card’s product to your analytics tool.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"afterInstantSearchSwatchClick",
		({ swatchButton, hitEl, optionValue }) => {
			window.dataLayer.push({
				event: "swatch_selected",
				option_value: optionValue,
				product_id: hitEl.dataset.algoliaObjectid,
				variant_id: swatchButton.dataset.variantId,
			});
		},
	);
});

`beforeInstantSearchStartAddWidgets`

Add InstantSearch widgets to the search results page. You can add the following widgets:

Returns

array

InstantSearch widgets.

Examples

Add a custom widget

Add a searchBox widget before InstantSearch adds default widgets.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeInstantSearchStartAddWidgets",
		() => {
			// Not all widgets are available
			const { searchBox } = window.algoliaShopify.externals.widgets;

			const searchBoxWidget = searchBox({
				container: "#search-box",
			});

			return [searchBoxWidget];
		},
	);
});

`afterInstantSearchStartRemoveDefaultWidgets`

Remove default widgets from the search results page. You can remove these widgets (widget.$$widgetType):

ais.sortBy
ais.searchBox
ais.stats
ais.hits
ais.pagination

Parameters

array

Default InstantSearch widgets.

Returns

array

Widgets to remove.

Examples

Remove a default widget

Remove the default pagination widget.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"afterInstantSearchStartRemoveDefaultWidgets",
		(defaultWidgets) => {
			// Find and return the default pagination widget to remove it
			const defaultPaginationWidget = defaultWidgets.find(
				(widget) => widget.$$widgetType === "ais.pagination",
			);

			return [defaultPaginationWidget];
		},
	);
});

`beforeInstantSearchFacetSearchablePlaceholder`

Changes the searchablePlaceholder for facet search.

Use beforeInstantSearchFacetParamsOptions instead.

Parameters

string

Default placeholder text.

Returns

string

Modified placeholder text.

Examples

Change the facet search placeholder

Override the facet search placeholder text.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeInstantSearchFacetSearchablePlaceholder",
		(placeholder) => "Search facets:",
	);
});

`beforeInstantSearchFacetParamsOptions`

Update widget parameters before they’re rendered.

Parameters

object

Widget parameters. Parameters depend on the widget type. Use facet.type to determine the widget.

object

Facet metadata (read-only):

title
name
type (refinement parameters)
- slider: rangeSlider
- menu: menu
- conjunctive: refinementList
- disjunctive: refinementList

Returns

object

Modified widget parameters.

Examples

Customize facet widget parameters

Adjust facet widget parameters based on facet.title or facet.type.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeInstantSearchFacetParamsOptions",
		(params, facet) => {
			if (facet.title == "Tags") {
				return {
					...params,
					limit: 5,
					templates: {
						searchableNoResults(data, { html }) {
							return html`<span>No results</span>`;
						},
					},
				};
			}

			if (facet.title == "Vendor") {
				return {
					...params,
					transformItems(items) {
						return items.map((item) => ({
							...item,
							label: item.label.toUpperCase(),
						}));
					},
				};
			}

			if (facet.type == "slider") {
				return {
					...params,
					pips: false,
					tooltips: true,
				};
			}

			return {
				...params,
			};
		},
	);
});

`beforeInstantSearchFacetPanelOptions`

Update the panel parameters before they’re rendered.

Parameters

object

Panel parameters. For more information, see panel.

object

Facet metadata (read-only):

title
name

Returns

object

Modified panel parameters.

Examples

Customize panel parameters

Customize panel templates like header, footer, and searchableNoResults.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeInstantSearchFacetPanelOptions",
		(params, facet) => {
			if (facet.name == "tags" || facet.title == "Tags") {
				return {
					...params,
					templates: {
						// To avoid duplicate headers use the `beforeInstantSearchMainTemplate` hook and remove the  'ais-facet-dropdown-wrapper' container
						header(options, { html }) {
							if (options.results) {
								return html`<span class="ais-facet--header">Tags Header (${options.results.nbHits} results)</span>`;
							}
						},
					},
				};
			}

			if (facet.type == "disjunctive") {
				return {
					...params,
					templates: {
						footer(options, { html }) {
							if (options.results) {
								return html`<span class="ais-facet--footer">Disjunctive footer (${options.results.nbHits} results)</span>`;
							}
						},
						searchableNoResults(data, { html }) {
							return html`<span>No results</span>`;
						},
					},
				};
			}

			return {
				...params,
			};
		},
	);
});

`beforeInstantSearchInitSearchSortOrders`

Transform sort order before they’re rendered.

Parameters

object[]

Sort orders, spread as individual arguments. The last argument is reserved for internal use: use rest syntax and slice(0, -1) to collect the sort order objects. Each has:

label (string): display name for the sort order
value (string): name for the sort order

Returns

array

Modified sort orders.

Examples

Add a custom sort order

Add a custom sort option to the sort-by widget.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeInstantSearchInitSearchSortOrders", 
		(...hookArgs) => {
			const indexPrefix = algoliaShopify.config.index_prefix;
			const sortOrders = hookArgs.slice(0, -1); // Drop the trailing internal argument

			const replicaName = `price_asc_virtual`; 
			const primaryIndex = `${indexPrefix}products`;
			const sortOrderIndex = `${primaryIndex}_${replicaName}`;

			sortOrders.push({
				label: 'Lowest Price',
				value: sortOrderIndex, // shopify_products_price_asc_virtual
			});
			return sortOrders;
		}
	);
});

`beforeInstantSearchInitCollectionSortOrders`

Transform the sort order for collections.

Parameters

object[]

Sort orders, spread as individual arguments. The last argument is reserved for internal use: use rest syntax and slice(0, -1) to collect the sort order objects. Each has:

label (string): display name for the sort order
value (string): name for the sort order

Returns

array

Modified sort orders.

Examples

Add a custom collection sort order

Add a custom sort option for collections.

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeInstantSearchInitCollectionSortOrders", 
		(...hookArgs) => {
			const indexPrefix = algoliaShopify.config.index_prefix;
			const sortOrders = hookArgs.slice(0, -1); // Drop the trailing internal argument

			const replicaName = `price_asc_virtual`; 
			const primaryIndex = `${indexPrefix}products`;
			const sortOrderIndex = `${primaryIndex}_${replicaName}`;

			sortOrders.push({
				label: 'Lowest Price',
				value: sortOrderIndex, // shopify_products_price_asc_virtual
			});
			return sortOrders;
		}
	);
});

`afterInstantSearchHitClickAction` (deprecated)

This hook is deprecated. Use beforeInstantSearchProductTemplate instead.

Runs after a user clicks a search result. Return a function to override the default click behavior.

Parameters

any

First parameter (unused).

Parameters

array

Transformed items.

array

Original items.

Returns

array

Modified items.

`afterISStartRemoveDefaultWidget` (deprecated)

This hook is deprecated. Use afterInstantSearchStartRemoveDefaultWidgets instead.

Remove default widgets from the search results page. You can remove these widgets (widget.widgetType):

ais.sortBy
ais.searchBox
ais.stats
ais.hits
ais.pagination

rangeSlider
menu
refinementList
searchBox
stats
sortBy
clearRefinements
panel
hits
pagination
configure

Returns

array

InstantSearch widgets.

`beforeISInitCollectionSortOrdersArray` (deprecated)

This hook is deprecated. Use beforeInstantSearchInitCollectionSortOrders instead.

Transform the sort order for collections.

Parameters

array

Sort orders.

Returns

array

Modified sort orders.

​beforeInstantSearchAsyncFunction

​Parameters

​Returns

​Examples

​beforeInstantSearchConfigurationOptions

​Parameters

​Returns

​Examples

​beforeInstantSearchOptions

​Parameters

​Returns

​Examples

​beforeInstantSearchAllowParamsArray

​Parameters

​Returns

​Examples

​beforeInstantSearchFiltersString

​Parameters

​Returns

​Examples

​beforeInstantSearchRuleContexts

​Parameters

​Returns

​Examples

​beforeInstantSearchMainTemplate

​Parameters

​Returns

​Examples

​beforeInstantSearchProductTemplate

​Parameters

​Returns

​Examples

​beforeInstantSearchNoResultTemplate

​Parameters

​Returns

​Examples

​beforeInstantSearchStatsTemplate

​Parameters

​Returns

​Examples

​beforeInstantSearchTransformItems

​Parameters

​Returns

​Examples

​beforeInstantSearchSwatchOptionResolver

​Parameters

​Returns

​Examples

​afterInstantSearchSwatchClick

​Parameters

​Examples

​beforeInstantSearchStartAddWidgets

​Returns

​Examples

​afterInstantSearchStartRemoveDefaultWidgets

​Parameters

​Returns

​Examples

​beforeInstantSearchFacetSearchablePlaceholder

​Parameters

​Returns

​Examples

​beforeInstantSearchFacetParamsOptions

​Parameters

​Returns

​Examples

​beforeInstantSearchFacetPanelOptions

​Parameters

​Returns

​Examples

​beforeInstantSearchInitSearchSortOrders

​Parameters

​Returns

​Examples

​beforeInstantSearchInitCollectionSortOrders

​Parameters

​Returns

​Examples

​afterInstantSearchHitClickAction (deprecated)

​Parameters

`beforeInstantSearchAsyncFunction`

Parameters

Returns

Examples

`beforeInstantSearchConfigurationOptions`

Parameters

Returns

Examples

`beforeInstantSearchOptions`

Parameters

Returns

Examples

`beforeInstantSearchAllowParamsArray`

Parameters

Returns

Examples

`beforeInstantSearchFiltersString`

Parameters

Returns

Examples

`beforeInstantSearchRuleContexts`

Parameters

Returns

Examples

`beforeInstantSearchMainTemplate`

Parameters

Returns

Examples

`beforeInstantSearchProductTemplate`

Parameters

Returns

Examples

`beforeInstantSearchNoResultTemplate`

Parameters

Returns

Examples

`beforeInstantSearchStatsTemplate`

Parameters

Returns

Examples

`beforeInstantSearchTransformItems`

Parameters

Returns

Examples

`beforeInstantSearchSwatchOptionResolver`

Parameters

Returns

Examples

`afterInstantSearchSwatchClick`

Parameters

Examples

`beforeInstantSearchStartAddWidgets`

Returns

Examples

`afterInstantSearchStartRemoveDefaultWidgets`

Parameters

Returns

Examples

`beforeInstantSearchFacetSearchablePlaceholder`

Parameters

Returns

Examples

`beforeInstantSearchFacetParamsOptions`

Parameters

Returns

Examples

`beforeInstantSearchFacetPanelOptions`

Parameters

Returns

Examples

`beforeInstantSearchInitSearchSortOrders`

Parameters

Returns

Examples

`beforeInstantSearchInitCollectionSortOrders`

Parameters

Returns

Examples

`afterInstantSearchHitClickAction` (deprecated)

Parameters