chat - Algolia

This widget is and is subject to change in minor versions.

Signature

chat({
  container: string | HTMLElement,
  // Required parameter, either one of
  agentId?: string,
  transport?: object,
  // Optional parameters
  getSearchPageURL?: function,
  tools?: object,
  templates?: object,
  cssClasses?: object,
});

Import

import { chat } from "instantsearch.js/es/widgets";

Use the chat widget to display a chat interface that interacts with a generative AI assistant. See also: Agent Studio

Examples

JavaScript

chat({
  container: '#chat',
  agentId: '8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9',
});

Options

container

string | HTMLElement

required

The CSS Selector or HTMLElement to insert the widget into.

chat({
  container: "#chat",
});

agentId

string

The unique identifier of the agent to connect to. You can find the agentId in the Agent Studio dashboard.

JavaScript

chat({
  // ...
  agentId: '8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9',
});

transport

object

A custom transport object to handle the communication between the chat widget and the agent. The API endpoint must be compatible with Vercel AI SDK 5.

JavaScript

chat({
  // ...
  transport: {
    api: 'https://chatapi.example.com/api/v1/chat',
    headers: {
      'X-Session-Id': '8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9',
      'X-Api-Version': '2025-01-01',
    },
  },
});

getSearchPageURL

function

A function to return the URL of the main search page with the nextUiState. This is used to navigate to the main search page when the user clicks on “View all” in the search tool.

JavaScript

chat({
  // ...
  getSearchPageURL: (nextUiState) =>
    `/search?${qs.stringify(nextUiState)}`,
});

tools

object

An object defining the client-side tools that the agent can use to interact with your application. A tool’s name must match what is defined in the Agent Studio dashboard.

JavaScript

chat({
  // ...
  tools: {
    addToCart: {
      templates: {
        layout: ({ message, addToolResult }, { html }) => html`
        <div>
          <p>Add ${message.input.objectID} to the cart?</p>
          <button onClick=${async () => {
            // add the product to the cart
            await addProductToCart(message.input.objectID);
            // notify the agent that the tool has been used
            addToolResult({ output: {
              text: `added ${message.input.objectID} to cart`,
              done: true,
            }});
          }}>Add to cart</button>
        </div>
        `,
      },
      onToolCall: ({ addToolResult }) => addToolResult({ output: {} }),
    },
    viewProduct: {
      templates: {
        layout: ({ message, addToolResult }, { html }) => {
          if (!message.output) {
            return html`<span>Loading product...</span>`;
          }

          return html`
          <div>
            <h2>${message.output.productName}</h2>
            <p>${message.output.brand}</p>
            <img src="${message.output.imageUrl}" />
          </div>
          `;
        },
      },
      onToolCall: async ({ message, addToolResult }) => {
        addToolResult({
          // fetch product details from your index
          output: await fetchProductDetails(message.input.objectID),
        });
      },
    },
  },
});

templates

object

The templates to use for the widget.

JavaScript

chat({
  // ...
  templates: {
    // ...
  },
});

cssClasses

object

The CSS classes you can override:

root. The root element of the widget.
container. The container element.
header. The header section of the widget.
- root. The root element.
- clear. The clear button.
- close. The close button.
- maximize. The maximize button.
- title. The title element.
- titleIcon. The title icon element.
messages. The messages section of the widget.
- root. The root element.
- content. The scrollable content.
- scroll. The scroll container.
- scrollToBottom. The scroll to bottom button.
- scrollToBottomHidden. The hidden state of the scroll to bottom button.
message. The message in the messages section.
- root. The root element.
- container. The message container.
- leading. The leading element (e.g., avatar).
- content. The content element.
- message. The message text element.
- actions. The action buttons container.
- footer. The footer element.
prompt. The prompt section of the widget.
- root. The root element.
- actions. The actions container.
- body. The body element.
- footer. The footer element.
- header. The header element.
- submit. The submit button.
- textarea. The textarea element.
toggleButton. The toggle button of the widget.
- root. The root element.

JavaScript

chat({
  // ...
  cssClasses: {
    root: "MyCustomChat",
    container: "MyCustomChatContainer MyCustomChatContainer--subclass",
    header: {
      root: "MyCustomChatHeader",
      title: ["MyCustomChatHeaderTitle", "MyCustomChatHeaderTitle--subclass"],
      // ...
    },
    // ...
  },
});

Templates

You can customize parts of a widget’s UI using the Templates API. Each template includes an html function, which you can use as a tagged template. This function safely renders templates as HTML strings and works directly in the browser—no build step required. For details, see Templating your UI.

The html function is available in InstantSearch.js version 4.46.0 or later.

item

string | function

The template to use for each result. This template receives an object containing a single record. You can use Algolia’s highlighting feature with the highlight function, directly from the template system.

JavaScript

chat({
  // ...
  templates: {
    item(hit, { html, components }) {
      return html`
        <h2>${components.Highlight({ attribute: "name", hit })}</h2>
        <p>${hit.description}</p>
      `;
    },
  },
});

header

object

Templates to use for the header section of the widget.

clearLabelText. Accessible label for the clear button.
closeIcon. The close icon template.
closeLabel. Accessible label for the close button.
maximizeIcon. The maximize icon template. Receives a parameter containing { maximized: boolean } for conditional rendering.
maximizeLabelText. Accessible label for the maximize button.
minimizeIcon. The minimize icon template.
minimizeLabelText. Accessible label for the minimize button.
titleIcon. The title icon template (defaults to sparkles).
titleText. The title text to display.

JavaScript

chat({
  // ...
  templates: {
    // ...
    header: {
      maximizeIcon({ maximized }, { html }) => html`
        <span>${maximized ? '🔽' : '🔼'}</span>
      `,
      titleIcon(_, { html }) => html`<span>✨</span>`,
      titleText: 'My AI shopping assistant',
    },
  },
})

messages

object

Templates to use for the messages section of the widget.

copyToClipboardLabelText. Accessible label for the copy to clipboard action.
error. Custom template when there is an error loading messages.
loader. Custom loader template.
loaderText. Text to display in the loader.
regenerateLabelText. Accessible label for the regenerate action.
scrollToBottomLabelText. Accessible label for the scroll to bottom button.

JavaScript

chat({
  // ...
  templates: {
    // ...
    messages: {
      loader(_, { html }) => html`<span>Loading messages...</span>`,
      // ...
    },
  },
});

message

object

Templates to use for an individual message in the messages section of the widget.

messageLabelText. Accessible label for the message.
actionsLabelText. Accessible label for the actions container.

JavaScript

chat({
  // ...
  templates: {
    // ...
    message: {
      messageLabelText: 'Chat message',
      actionsLabelText: 'Message actions',
    },
  },
});

assistantMessage

object

Templates to use for messages that come from the chat assistant.

leading. The leading element (e.g., avatar).
footer. The footer element of the message.

JavaScript

chat({
  // ...
  templates: {
    // ...
    assistantMessage: {
      leading(_, { html }) => html`<img src="assistant-avatar.png" alt="Assistant avatar" />`,
      footer(_, { html }) => html`<span>Sent by AI Assistant</span>`,
    },
  },
});

userMessage

object

Templates to use for messages that come from the user.

leading. The leading element (e.g., avatar).
footer. The footer element of the message.

JavaScript

chat({
  // ...
  templates: {
    // ...
    userMessage: {
      leading(_, { html }) => html`<img src="user-avatar.png" alt="User avatar" />`,
      footer(_, { html }) => html`<span>Sent by You</span>`,
    },
  },
});

prompt

object

Templates to use for the prompt section of the widget.

disclaimerText. Disclaimer text shown in the prompt footer.
emptyMessageTooltipText. Tooltip for the submit button when message is empty.
footer. Custom footer template.
header. Custom header template.
sendMessageTooltipText. Tooltip for the send button.
stopResponseTooltipText. Tooltip for the stop button.
textareaLabelText. Accessible label for the textarea.
textareaPlaceholderText. Placeholder text for the textarea.

JavaScript

chat({
  // ...
  templates: {
    // ...
    prompt: {
      header(_, { html }) => html`<span>Ask me anything</span>`,
      footer(_, { html }) => html`
        <a href="https://example.com/privacy-policy">
          Privacy policy
        </a>
      `,
      // ...
    },
  },
});

toggleButton

object

Templates to use for the toggle button of the widget.

icon. Custom icon template. Receives a parameter containing { isOpen: boolean } for conditional rendering.

JavaScript

chat({
  // ...
  templates: {
    // ...
    toggleButton: {
      icon({ isOpen }, { html }) => html`<span>${isOpen ? '×' : '+'}</span>`,
    },
  },
});

HTML output

HTML

<div class="ais-Chat">
  <div class="ais-Chat-container">
    <div class="ais-ChatHeader">
      <span class="ais-ChatHeader-title">
        <span class="ais-ChatHeader-titleIcon"></span>
      </span>
      <div class="ais-ChatHeader-actions">
        <button class="ais-ChatHeader-clear"></button>
        <button class="ais-ChatHeader-maximize"></button>
        <button class="ais-ChatHeader-close" title="Close chat"></button>
      </div>
    </div>
    <div class="ais-ChatMessages">
      <div class="ais-ChatMessages-scroll ais-Scrollbar">
        <div class="ais-ChatMessages-content">
          ...
        </div>
      </div>
      <button
        class="ais-ChatMessages-scrollToBottom ais-ChatMessages-scrollToBottom--hidden"
      ></button>
    </div>
    <form class="ais-ChatPrompt">
      <div class="ais-ChatPrompt-body">
        <textarea class="ais-ChatPrompt-textarea ais-Scrollbar"></textarea>
        <div class="ais-ChatPrompt-actions">
          <button class="ais-ChatPrompt-submit"></button>
        </div>
      </div>
      <div class="ais-ChatPrompt-footer">
        <div class="ais-ChatPrompt-disclaimer"></div>
      </div>
    </form>
  </div>
  <button class="ais-ChatToggleButton"></button>
</div>

InstantSearch.js

​Import

​About this widget

​Examples

​Options

​Templates

​HTML output

Import

About this widget

Examples

Options

Templates

HTML output