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.
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
Returns
Examples
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
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
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
Change the chat title
JavaScript
Send an extra field to the agent
Send an extra field to the agent
Add properties to Follow these rules:For more on turn context, see Per-turn context.
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
-
Copy the existing context properties with
...options.contextbefore adding your own. This preserveslanguageand the app’s product and collection properties. -
Always return an
optionsobject. - 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.
product_material example:Agent instructions
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
Returns
Examples
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
Returns
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
Add a price filter to the stock filter
JavaScript
Remove the stock filter
Remove the stock filter
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
Template options including
html, item, and components.
The item has a prompt property containing the suggested question.Returns
Examples
Customize search box suggestions
Customize search box suggestions
JavaScript
Other hooks for search box suggestions
These Autocomplete hooks also apply to search box suggestions:- Use
beforeAutocompletePluginOptionswithpluginName: "promptSuggestions"to change the search client, index name (indexName), or search parameters, such ashitsPerPage. - Use
beforeAutocompleteConfigurationOptionsto configure search box suggestions. For these suggestions,context.sourceIdis"promptSuggestionsPlugin". - Use
beforeAutocompletePluginsArrayto remove the suggestions plugin. - When you customize the Autocomplete menu with
beforeAutocompleteMainTemplate, includeelements.promptSuggestionsPluginin the returned template to display the search box suggestions.