Skip to main content
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.

Returns

Template to render inside the button.

Examples

JavaScript

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 and overrides any changes to them. 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. Other options you can set include context, feedback, suggestions, and getSearchPageURL.

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

JavaScript
Add properties to options.context to send more information to the agent with every question. This example sends a single-line text product metafield on product pages. Add it to your theme’s theme.liquid file.
HTML
Follow these rules:
  • Copy the existing context properties with ...options.context before adding your own. This preserves language and the app’s product and collection properties.
  • Always return an options object.
  • Use a flat object with string values. Each value must contain at least one non-whitespace character and be at most 1,024 UTF-8 bytes. Use at most 32 properties. Property names must contain 1 to 64 ASCII letters, numbers, periods, underscores, or hyphens. Keep the total context within the 4,096-byte limit, including the properties the app sends. On product pages, the app already sends up to about 2.6 KB. The app doesn’t automatically shorten or validate the properties you add. If the context violates these rules, Agent Studio rejects each question with an HTTP 422 error, and the chat displays an error.
  • If you rename or remove the app’s properties, update the agent’s instructions to match.
The agent doesn’t know what a new field means until you tell it. Add a line about the field to the agent’s instructions. For the product_material example:
Agent instructions
For more on turn context, see Per-turn context.

beforeAiModeProductTemplate

Template for each product card in the chat carousel. Include ${cart} in your custom card template where you want the Add to cart button to appear. 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.
boolean
Whether the store shows one result per product.
Product URL.

Returns

Template to render.

Examples

JavaScript

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

JavaScript
JavaScript

beforeAutocompletePromptSuggestionsTemplate

Template for each search box suggestion under the AI Mode header in the Autocomplete menu. It works like beforeAutocompleteSuggestionsTemplate. Selecting a suggestion opens AI Mode and asks that question, so the item doesn’t link anywhere.

Parameters

Default template.
object
Template options including html, item, and components. The item has a prompt property containing the suggested question.

Returns

Template to render.

Examples

JavaScript
The default template uses these classes:

Other hooks for search box suggestions

These Autocomplete hooks also apply to search box suggestions:
Last modified on November 18, 2026