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

Shopify apps can’t modify theme code directly. To integrate Autocomplete and InstantSearch, use the Algolia AI Search & Discovery app’s App Embed and App Blocks.For more information, see:

Hooks are functions that run at specific points while the Algolia AI Search & Discovery app loads and runs. Use hooks to customize the app’s behavior. To see which hooks are available for your store, run window.algoliaShopify.hooks.allowedHooks in your browser’s developer tools.

Screenshot of a code snippet showing 'algoliaShopify.hooks.allowedHooks' with hook names like 'beforeAutocompleteOptions' and 'beforeInstantSearchOptions'.

Add custom hooks

To add custom hooks, add a new JavaScript file, register the hook, and include that file in your theme.

Add a new JavaScript file

In your store’s Shopify admin, go to Sales channels > Online Store > Themes.
Select the theme you want to edit and click Click for more theme actions > Edit code.
In the assets section, click New file.
Enter a filename, for example, algolia_custom_hooks.js.

Open the custom hooks JavaScript file you created in the last step (for example, algolia_custom_hooks.js).

Add an event listener to the algolia.hooks.initialize event and call the algoliaShopify.hooks.registerHook function. For example:

JavaScript

document.addEventListener("algolia.hooks.initialize",
  function () {
    algoliaShopify.hooks.registerHook(
      "beforeAutocompleteOptions",
      function (options) {
        // ...
      },
    );
  }
);

Include the JavaScript file in your theme

Under layouts, open the theme.liquid file.
Go to the bottom of the theme.liquid file and add the following code just before the </body> tag. Replace NEW_FILE with the JavaScript file that contains your custom hooks, for example algolia_custom_hooks:
HTML
<script src="{{ 'CUSTOM_HOOKS_FILE.js' | asset_url }}" defer="defer"></script>
Save the file.

Hook names

Your hook function must return the expected type. The hook name suffix indicates the expected return type:

Hook name ends with	Expected return type
`Options`	Object
`Template`	Tagged template literal
`Array`	Array of strings or objects
`String`	String
`Number`	Number
`Action`	Function

​Add custom hooks

​Hook names

​See also

Add custom hooks

Hook names

See also