Integrations / Shopify

From December 31, 2023, Algolia’s Search and Discovery application can’t modify the coding of Shopify themes. For more information, refer to Shopify’s Asset API documentation. As an alternative, Algolia offers Shopify’s App Embed and App Blocks features for Autocomplete and InstantSearch interfaces. For more information, refer to the Quick start and Shopify Algolia configuration documentation.

How hooks works

Adjust the logic of the Autocomplete and InstantSearch integration by registering a custom method in your JavaScript file.

The extension provides hooks to help you add or change parameters for the implementation. The algoliaShopify window variable is an object that handles the setting and firing of events in the Autocomplete and InstantSearch frontend implementation. To view the available events, visit your Shopify store and type algoliaShopify.hooks.allowedHooks into your browser’s API console:

An example of allowed hooks

Customizing

Five kinds of hooks are available. Each hook requires a different return value.

  • Options expects an object
  • Templates expects a Tagged Template Literal wrapped around html.
    • example: html`<h1>Algolia</h1>`
  • Array expects an array of objects or strings
  • String expects a string
  • Number expects a number
  • Action expects a function

Autocomplete hooks

  • beforeAutocompleteOptions(options)
  • beforeAutocompleteFiltersString(defaultFilter)
  • beforeAutocompleteRedirectUrlOptions(options)
    • Used to modify the default parameter options of the createRedirectUrlPlugin
    • the hook must return an options value
  • beforeAutocompleteMainTemplate(defaultTemplate, templateOptions, elements, displaySuggestions), beforeAutocompleteMainProductsTemplate(defaultTemplate, templateOptions, elements)
    • Used to modify the HTML template that renders the Autocomplete panel.
    • Renders an Autocomplete multi-panel layout
  • beforeAutocompleteNoResultsTemplate(defaultTemplate, templateOptions)
    • Used to modify the HTML template that renders the Autocomplete panel.
    • Renders a no results section when there are no hits
  • beforeAutocompleteHeaderTemplate(defaultTemplate, templateOptions)
    • Renders a header section at the top of the Autocomplete panel
  • beforeAutocompleteFooterTemplate(defaultTemplate, templateOptions)
    • Renders a footer section at the bottom of the Autocomplete panel
  • beforeAutocompleteProductTemplate(defaultTemplate, templateOptions, distinct, itemLink)
    • Renders the Autocomplete menu’s product section
  • beforeAutocompleteArticlesTemplate(templateOptions, itemLink)
    • Renders the Autocomplete menu’s articles section
  • beforeAutocompleteCollectionsTemplate(defaultTemplate, templateOptions, itemLink)
    • Renders the Autocomplete menu’s collections section
  • beforeAutocompletePagesTemplate(defaultTemplate, templateOptions, itemLink)
    • Renders the Autocomplete menu’s pages section
  • beforeAutocompleteSuggestionsTemplate(defaultTemplate, templateOptions)
    • Renders the Autocomplete menu’s suggestions section
  • afterAutocompleteProductClickAction(undefined, line_item)
    • Used to execute a function after a product is clicked

Examples of Autocomplete hooks

Example of beforeAutocompleteOptions(options) hook:

1
2
3
4
5
6
7
8
9
// Modify default `options`
document.addEventListener('algolia.hooks.initialize', function() {
  algoliaShopify.hooks.registerHook('beforeAutocompleteOptions', function(options) {
    // Modify default options, then return them
    options.placeholder = "Search Our Products";
    return options;
  });
});

Example of beforeAutocompleteFiltersString(defaultFilter) hook:

1
2
3
4
5
6
7
// Omit `_defaultFilter` and return a custom filter
document.addEventListener('algolia.hooks.initialize', function() {
  algoliaShopify.hooks.registerHook('beforeAutocompleteFiltersString', function(_defaultFilter) {
    // Modify or replace the default string, then return a string
    return 'price > 17';
  });
});

Example of beforeAutocompleteHeaderTemplate(defaultTemplate, templateOptions) hook:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// Omit `defaultTemplate` and return a custom template
document.addEventListener('algolia.hooks.initialize', function() {
  algoliaShopify.hooks.registerHook('beforeAutocompleteHeaderTemplate', function(_defaultTemplate, templateOptions, resource) {
    // Modify default options, then return them
    const { html, state } = templateOptions;
    const { query } = state;
    return html`
      <div class="aa-SourceHeader">
        <span class="aa-SourceHeaderTitle">
          ${`Results for "${query}"`}
        </span>
        <div class="aa-SourceHeaderLine" />
      </div>
    `;
  });
});

InstantSearch hooks

  • beforeInstantSearchConfigurationOptions(options)
  • beforeInstantSearchOptions(options)
    • Contains colors, distinct, facets, hitsPerPage, selector, and sortOrders
  • beforeInstantSearchAllowParamsArray(allowParamsArray)
    • Preserves the URL parameters when navigating through the search results
  • beforeInstantSearchFiltersString(defaultFilter)
  • beforeInstantSearchMainTemplate(defaultTemplate, data, html)
    • Renders the main template container
  • beforeInstantSearchProductTemplate(defaultTemplate, data, html, components)
    • Renders the product template
  • beforeInstantSearchNoResultTemplate(defaultTemplate, html)
    • Renders the no results template
  • beforeInstantSearchFacetItemTemplate(defaultTemplate, item, html)
    • Renders the facet items
  • beforeInstantSearchShowMoreTemplate(defaultTemplate, data, html)
  • beforeInstantSearchStatsTemplate(defaultTemplate, data, html)
  • beforeISTransformItems(transformedItems, items)
    • Used to modify items before they’re rendered
  • afterISStartRemoveDefaultWidget(_, defaultWidgets)
  • afterInstantSearchHitClickAction(_, hit)
    • Used to execute a function after a hit is clicked
  • beforeInstantSearchFacetLimitNumber(limit)
  • beforeISFacetSearchablePlaceholderString(placeHolder, facet)
  • beforeISFacetSearchableNoResultsString(noResults, facet)
  • beforeInstantSearchFacetHeaderString(facetTitle, facet)
    • Used to modify the facet header string
  • beforeInstantSearchFacetTransformItemsOptions(transformedItems, items)
  • beforeISearchInitSortOrdersArray(transformedSortOrders, sortOrder)
  • beforeISInitCollectionSortOrdersArray(transformedSortOrders, sortOrder)
    • Used to modify the default sort orders.

Examples of InstantSearch hooks

Example of beforeInstantSearchConfigurationOptions(options) hook:

1
2
3
4
5
6
7
8
9
// Modify default `options`
document.addEventListener('algolia.hooks.initialize', function() {
  algoliaShopify.hooks.registerHook('beforeInstantSearchConfigurationOptions', function(options) {
    // Modify default options, then return them
    options.numberLocale: 'fr';
    options.stalledSearchDelay: 500;
    return options;
  });
});

Example of beforeInstantSearchAllowParamsArray(allowParamsArray) hook:

1
2
3
4
5
6
7
8
// Modify default `allowParamsArray`
document.addEventListener('algolia.hooks.initialize', function() {
  algoliaShopify.hooks.registerHook('beforeInstantSearchAllowParamsArray', function(allowParamsArray) {
    // Modify default array, then return an array
    allowParamsArray.push('ref');
    return allowParamsArray;
  });
});

Example of beforeInstantSearchFiltersString(defaultFilter) hook:

1
2
3
4
5
6
7
8
9
10
11
12
// Modify default `defaultFilter` if it exists
document.addEventListener('algolia.hooks.initialize', function() {
  algoliaShopify.hooks.registerHook('beforeInstantSearchFiltersString', function(defaultFilter) {
    // Modify or replace the default string, then return a string
    if(defaultFilter) {
      return defaultFilter + ' AND price > 5'
    }
    else {
      return 'price > 5'
    }
  });
});

Example of beforeInstantSearchFacetLimitNumber(limit) hook:

1
2
3
4
5
6
7
// Modify default `limit`
document.addEventListener('algolia.hooks.initialize', function() {
  algoliaShopify.hooks.registerHook('beforeInstantSearchFacetLimitNumber', function(limit) {
    // Modify default limit, then return a number
    return 12;
  });
});

Insights hook example

  • beforeAlgoliaAnalyticsOptions(options)
  • beforeAddToCartSelectorString(selector)
    • Used to modify the selector string for the add to cart button

Example of beforeAlgoliaAnalyticsOptions(options) hook:

1
2
3
4
5
6
7
8
// Modify default `options`
document.addEventListener('algolia.hooks.initialize', function() {
  algoliaShopify.hooks.registerHook('beforeAlgoliaAnalyticsOptions', function(options) {
    // Modify default options, then return them
    options.userToken = 'd41951d5-4d0a-4907-8c1f-e98f6360e44d'; // random UUID;
    return options;
  });
});

Example of beforeAddToCartSelectorString(selector) hook:

1
2
3
4
5
6
7
8
// Modify default `options`
document.addEventListener('algolia.hooks.initialize', function() {
  algoliaShopify.hooks.registerHook('beforeAddToCartSelectorString', function(_selector) {
    // The default selector is '[name="add"]'
    // Return a CSS selector
    return '#add-to-cart';
  });
});
Did you find this page helpful?