Provides an AI-powered conversational search interface with support for Algolia’s AI Search capabilities.
Usage
import instantsearch from 'instantsearch.js';
import { chat } from 'instantsearch.js/es/widgets';
const search = instantsearch({
indexName: 'instant_search',
searchClient
});
search.addWidgets([
chat({
container: '#chat',
apiKey: 'YOUR_API_KEY',
indexName: 'instant_search'
})
]);
search.start();
Parameters
container
string | HTMLElement
required
CSS selector or HTMLElement to insert the widget.
Your Algolia API key with AI Search access.
The name of the index to search in.
Whether to resume the previous conversation on page load.
Function to return the URL for the main search page. Used for “View all” links.(nextUiState: IndexUiState) => string
Custom client-side tools to add to the chat.Each tool is an object with:
templates.layout: Template for rendering the tool output
Templates to customize the chat interface.
Template for rendering product items in search results. Receives hit data.
Templates for the chat header.
Template for the entire header.
Title text for the chat header.
Template for the close icon.
Template for the minimize icon.
Template for the maximize icon.
Templates for chat messages.
Template for the loading state.
Template for error messages.
Templates for the input prompt.
Template for the prompt layout.
Placeholder text for the input.
Templates for the toggle button.
Template for the button icon.
Template for prompt suggestions.
CSS classes to add to the widget elements.
CSS class for the root element.
CSS class for the header.
CSS class for the messages container.
CSS class for the prompt area.
CSS class for the toggle button.
Examples
Basic chat
chat({
container: '#chat',
apiKey: 'YOUR_API_KEY',
indexName: 'products'
});
Custom item template
chat({
container: '#chat',
apiKey: 'YOUR_API_KEY',
indexName: 'products',
templates: {
item(hit, { html }) {
return html`
<div class="chat-product">
<img src="${hit.image}" alt="${hit.name}" />
<div>
<h4>${hit.name}</h4>
<p>$${hit.price}</p>
</div>
</div>
`;
}
}
});
chat({
container: '#chat',
apiKey: 'YOUR_API_KEY',
indexName: 'products',
templates: {
header: {
titleText: 'Shopping Assistant',
closeLabelText: 'Close chat',
clearLabelText: 'Clear conversation'
}
}
});
With search page integration
import qs from 'qs';
chat({
container: '#chat',
apiKey: 'YOUR_API_KEY',
indexName: 'products',
getSearchPageURL(nextUiState) {
return `/search?${qs.stringify(nextUiState)}`;
}
});
Custom prompt placeholder
chat({
container: '#chat',
apiKey: 'YOUR_API_KEY',
indexName: 'products',
templates: {
prompt: {
textareaPlaceholderText: 'Ask me about our products...'
}
}
});
With suggestions
chat({
container: '#chat',
apiKey: 'YOUR_API_KEY',
indexName: 'products',
templates: {
suggestions({ suggestions, onSuggestionClick }) {
return `
<div class="suggestions">
${suggestions.map(s => `
<button onclick="${() => onSuggestionClick(s)}">
${s}
</button>
`).join('')}
</div>
`;
}
}
});
Resume conversation
chat({
container: '#chat',
apiKey: 'YOUR_API_KEY',
indexName: 'products',
resume: true // Restore previous conversation
});
import { SearchIndexToolType } from 'instantsearch.js/es/widgets';
chat({
container: '#chat',
apiKey: 'YOUR_API_KEY',
indexName: 'products',
tools: {
[SearchIndexToolType]: {
templates: {
layout({ message }) {
const hits = message?.output?.hits || [];
return `
<div class="custom-results">
${hits.map(hit => `<div>${hit.name}</div>`).join('')}
</div>
`;
}
}
}
}
});
HTML output
<div class="ais-Chat">
<button class="ais-Chat-toggleButton">
<!-- Toggle button content -->
</button>
<div class="ais-Chat-dialog">
<div class="ais-Chat-header">
<h3>Chat</h3>
<button class="close">×</button>
</div>
<div class="ais-Chat-messages">
<div class="ais-Chat-message ais-Chat-message--user">
<!-- User message -->
</div>
<div class="ais-Chat-message ais-Chat-message--assistant">
<!-- Assistant message -->
</div>
</div>
<div class="ais-Chat-prompt">
<textarea placeholder="Ask a question..."></textarea>
<button>Send</button>
</div>
</div>
</div>
Notes
- Requires Algolia AI Search to be enabled on your account.
- The chat maintains conversation history.
- Supports multiple interaction patterns: search, recommend, filters.
- Messages are stored locally and can be resumed.
- The widget handles streaming responses automatically.