> ## Documentation Index
> Fetch the complete documentation index at: https://www.algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Mode custom hooks
> Custom hooks that change the AI Mode button, chat, product cards, and filters.
This is a **beta feature** according to [Algolia's Terms of Service ("Beta Services")](https://www.algolia.com/policies/terms/).
> [!NOTE]
>
> 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](https://www.algolia.com/doc/integration/shopify/getting-started/configuration.md#search-client-version) to **Version 5**.
> If you use custom storefront JavaScript, follow the [version 5 upgrade guide](https://www.algolia.com/doc/libraries/sdk/upgrade/javascript.md).
> Support for version 4 ends on August 14, 2026.
These hooks change [AI Mode](https://www.algolia.com/doc/integration/shopify/building-search-ui/ai-mode.md).
Register them on the `algolia.hooks.initialize` event, like the other [custom hooks](https://www.algolia.com/doc/integration/shopify/building-search-ui/frontend-custom-events).
## `beforeAutocompleteAiModeTemplate`
Template for the content of the **AI Mode** button in the Autocomplete menu.
The default content is a star symbol followed by the `aiModeTitle` label.
### Parameters
**defaultTemplate**
Default template.
**templateOptions** `object`
Template options.
**html** `function`
Tagged template function to build the template.
### Returns
**template**
Template to render inside the button.
### Examples
> [accordion] Change the button content
>
> ```js JavaScript icon=code theme={"system"}
> document.addEventListener("algolia.hooks.initialize", () => {
> algoliaShopify.hooks.registerHook(
> "beforeAutocompleteAiModeTemplate",
> (_defaultTemplate, { html }) => {
> return html`Ask our assistant`;
> },
> );
> });
> ```
## `beforeAiModeOptions`
Changes the options of the InstantSearch [`chat` widget](https://www.algolia.com/doc/api-reference/widgets/chat/js) before it renders.
Use it to change text, templates, and other widget options.
The app sets `container`, `agentId`, `id`, and `transport` after the hook runs.
The app overrides any changes to these options.
Hooks run after translations,
so text you set in a hook overrides the [translated labels](https://www.algolia.com/doc/integration/shopify/building-search-ui/ai-mode.md#translate-labels).
### Parameters
**options** `object`
Chat widget options, such as `templates.header.titleText`, `templates.header.clearLabelText`, `templates.prompt.textareaPlaceholderText`, `templates.prompt.disclaimerText`, `templates.loaderText`, `templates.item`, and `templates.messages.error`.
For the full list, see the [`chat` widget reference](https://www.algolia.com/doc/api-reference/widgets/chat/js).
### Returns
**options** `object`
Return the modified options.
If the hook returns nothing,
AI Mode keeps the defaults and logs `beforeAiModeOptions must return the options. Using the defaults.` to the console.
If the hook throws an error, AI Mode also keeps the defaults.
### Examples
> [accordion] Change the chat title
>
> ```js JavaScript icon=code theme={"system"}
> document.addEventListener("algolia.hooks.initialize", () => {
> algoliaShopify.hooks.registerHook("beforeAiModeOptions", (options) => ({
> ...options,
> templates: {
> ...options.templates,
> header: {
> ...options.templates.header,
> titleText: "Shop assistant",
> },
> },
> }));
> });
> ```
## `beforeAiModeProductTemplate`
Template for each product card in the chat carousel.
Click tracking also works for custom cards.
If the answer is still loading, clicking a link in a custom card stops it.
### Parameters
**defaultTemplate**
Default template.
**templateOptions** `object`
Template options.
**html** `function`
Tagged template function to build the template.
**item** `object`
Product record, with attributes such as `title`, `handle`, `price`, and `image`.
**distinct** `boolean`
Whether the store shows one result per product.
**itemLink** `string`
Product URL.
### Returns
**template**
Template to render.
### Examples
> [accordion] Customize product cards
>
> ```js JavaScript icon=code theme={"system"}
> document.addEventListener("algolia.hooks.initialize", () => {
> algoliaShopify.hooks.registerHook(
> "beforeAiModeProductTemplate",
> (_defaultTemplate, { html, item }, _distinct, itemLink) => {
> return html`
> Custom ${item.title}
> `;
> },
> );
> });
> ```
## `beforeAiModeFiltersString`
Changes the stock filter (A filter is a condition that limits which records Algolia returns. Filters often use one or more facet-value pairs, such as brand:Apple AND color:red. You can also filter by numeric values, dates, tags, booleans, or geographic constraints.) that AI Mode sends with each question.
The `beforeAutocompleteFiltersString` hook doesn't apply to AI Mode.
AI Mode adds the returned string to the agent's own filter with `AND`.
The hook can't remove the agent's filter.
For examples of what AI Mode sends, see [Filter products](https://www.algolia.com/doc/integration/shopify/building-search-ui/ai-mode.md#filter-products).
### Parameters
**stockFilter** `string`
Filter that applies your store's out-of-stock setting.
Can be an empty string.
### Returns
**filters** `string`
Modified stock filter.
An empty string removes the stock filter, and the agent's filter still applies.
Use supported filter syntax, such as `A AND (B OR C)`.
Don't group `AND` conditions within an `OR` condition.
For the complete rules, see [Filters and boolean operators](https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/in-depth/combining-boolean-operators.md).
### Examples
> [accordion] Add a price filter to the stock filter
>
> ```js JavaScript icon=code theme={"system"}
> document.addEventListener("algolia.hooks.initialize", () => {
> algoliaShopify.hooks.registerHook(
> "beforeAiModeFiltersString",
> (stockFilter) => {
> return [stockFilter, "price < 100"].filter(Boolean).join(" AND ");
> },
> );
> });
> ```
> [accordion] Remove the stock filter
>
> ```js JavaScript icon=code theme={"system"}
> document.addEventListener("algolia.hooks.initialize", () => {
> algoliaShopify.hooks.registerHook("beforeAiModeFiltersString", () => {
> return "";
> });
> });
> ```
## See also
* [Autocomplete hooks](https://www.algolia.com/doc/integration/shopify/building-search-ui/autocomplete-hooks.md)