AI Mode custom hooks

This is a beta feature according to Algolia’s Terms of Service (“Beta Services”).

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.

These hooks change AI Mode. Register them on the algolia.hooks.initialize event, like the other custom hooks.

`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

Default template.

object

Template options.

Show child attributes

function

Tagged template function to build the template.

Returns

Template to render inside the button.

Examples

Change the button content

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAutocompleteAiModeTemplate",
		(_defaultTemplate, { html }) => {
			return html`<span>Ask our assistant</span>`;
		},
	);
});

`beforeAiModeOptions`

Changes the options of the InstantSearch chat widget 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.

Parameters

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.

Returns

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

Change the chat title

JavaScript

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

Default template.

object

Template options.

Show child attributes

function

Tagged template function to build the template.

object

Product record, with attributes such as title, handle, price, and image.

boolean

Whether the store shows one result per product.

string

Product URL.

Returns

Template to render.

Examples

Customize product cards

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAiModeProductTemplate",
		(_defaultTemplate, { html, item }, _distinct, itemLink) => {
			return html`
				<a href=${itemLink} class="custom-card">Custom ${item.title}</a>
			`;
		},
	);
});

`beforeAiModeFiltersString`

Changes the stock 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.

Parameters

string

Filter that applies your store’s out-of-stock setting. Can be an empty string.

Returns

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.

Examples

Add a price filter to the stock filter

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook(
		"beforeAiModeFiltersString",
		(stockFilter) => {
			return [stockFilter, "price < 100"].filter(Boolean).join(" AND ");
		},
	);
});

Remove the stock filter

JavaScript

document.addEventListener("algolia.hooks.initialize", () => {
	algoliaShopify.hooks.registerHook("beforeAiModeFiltersString", () => {
		return "";
	});
});

​beforeAutocompleteAiModeTemplate

​Parameters

​Returns

​Examples

​beforeAiModeOptions

​Parameters

​Returns

​Examples

​beforeAiModeProductTemplate

​Parameters

​Returns

​Examples

​beforeAiModeFiltersString

​Parameters

​Returns

​Examples

​See also

`beforeAutocompleteAiModeTemplate`

Parameters

Returns

Examples

`beforeAiModeOptions`

Parameters

Returns

Examples

`beforeAiModeProductTemplate`

Parameters

Returns

Examples

`beforeAiModeFiltersString`

Parameters

Returns

Examples

See also