Custom hook events

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:

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)
  • Used to modify parameter options of the Autocomplete menu
• 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.registerHook('beforeAutocompleteOptions', function(options) {
    // Modify default options, then return them
    options.placeholder = "Search Our Products";
    return options;
  });
})

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.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

• beforeInstantSearchOptions(options)
  • Used to modify default instantsearch options
• beforeInstantSearchAllowParamsArray(allowParamsArray)
  • Preserves the URL parameters when navigating through the search results
• beforeInstantSearchMainTemplate(defaultTemplate, data)
  • Renders the main template container
• beforeInstantSearchProductTemplate(defaultTemplate, data)
  • Renders the product template
• beforeInstantSearchNoResultTemplate(defaultTemplate, html)
  • Renders the no results template
• beforeInstantSearchFacetItemTemplate(defaultTemplate, item, html)
  • Renders the facet items
• beforeInstantSearchShowMoreTemplate(defaultTemplate, data, html)
  • Renders the show more button
• beforeInstantSearchStatsTemplate(defaultTemplate, data, html)
  • Renders the stats
• beforeISTransformItems(transformedItems, items)
  • Used to modify items before they’re rendered
• afterISStartRemoveDefaultWidget(_, defaultWidgets)
  • Removes the default widgets from the InstantSearch page
• afterInstantSearchHitClickAction(_, hit)
  • Used to execute a function after a hit is clicked
• beforeInstantSearchFacetLimitNumber(limit)
  • Used to modify the default number of facets
  • The default limit is 10
• beforeISFacetSearchablePlaceholderString(placeHolder, facet)
  • Used to modify the placeholder string for a searchable facet
• beforeISFacetSearchableNoResultsString(noResults, facet)
  • Used to modify the no results string for a searchable facet
  • Return value can be a JavaScript template literal or a string
• beforeInstantSearchFacetHeaderString(facetTitle, facet)
  • Used to modify the facet header string
• beforeInstantSearchFacetTransformItemsOptions(transformedItems, items)
  • Used to modify facet items
• beforeISearchInitSortOrdersArray(transformedSortOrders, sortOrder)
  • Used to modify sort order
• beforeISInitCollectionSortOrdersArray(transformedSortOrders, sortOrder)
  • Used to modify the default sort orders.

Examples of InstantSearch hooks

Example of beforeInstantSearchOptions(options) hook:

1
2
3
4
5
6
7
8
9
// Modify default `options`
document.addEventListener('algolia.hooks.initialize', function() {
  algoliaShopify.registerHook('beforeInstantSearchOptions', 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.registerHook('beforeInstantSearchAllowParamsArray', function(allowParamsArray) {
    // Modify default array, then return an array
    allowParamsArray.push('ref');
    return allowParamsArray;
  });
})

Example of beforeInstantSearchFacetLimitNumber(limit) hook:

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

Insights hook example

• beforeAlgoliaAnalyticsOptions(options)
  • Used to modify parameter options of the Insights library
• 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.registerHook('beforeAlgoliaAnalyticsOptions', function(options) {
    // Modify default options, then return them
    options.userToken = 'd41951d5-4d0a-4907-8c1f-e98f6360e44d'; // random UUID;
    return options;
  });
})