Chat

Displays a chat interface to interact with a generative AI assistant built with Algolia Agent Studio.

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

For more information, see Agent Studio.

Signature

<Chat
  // Required prop, either one of
  agentId={string}
  transport={object}
  // Optional props (agentId only)
  feedback={boolean}
  requestOptions={object}
  // Optional props
  getSearchPageURL={function}
  tools={object}
  context={object | function}
  initialMessages={array}
  initialUserMessage={string}
  resume={boolean}
  persistence={boolean | object}
  disableTriggerValidation={boolean}
  onFinish={function}
  sendAutomaticallyWhen={function}
  requiresSearch={boolean}
  showReasoning={boolean}
  loaderPosition={string}
  shouldShowLoader={function}
  loaderShowDelay={number}
  loaderMinDuration={number}
  messagesProps={object}
  classNames={object}
  translations={object}
  layoutComponent={function}
  // Optional component props
  reasoningComponent={function}
  itemComponent={function}
  headerCloseIconComponent={function}
  headerMaximizeIconComponent={function}
  headerMinimizeIconComponent={function}
  headerTitleIconComponent={function}
  messagesErrorComponent={function}
  loaderComponent={function}
  promptFooterComponent={function}
  promptHeaderComponent={function}
  suggestionsComponent={function}

  ...props={ComponentProps<'div'>}
/>

Import

JavaScript

import { Chat } from "react-instantsearch";

About this widget

<Chat> is a widget to display a chat interface that interacts with a generative AI assistant.

See also: Agent Studio

<Chat> renders the chat panel but doesn’t provide a way to open it. Add one entry point to the same <InstantSearch> instance: the <ChatTrigger> widget, AI mode on a SearchBox or autocomplete, or an inline layout. Otherwise, the widget logs a development warning. To silence it, set disableTriggerValidation to true.

Examples

JavaScript

import React from "react";
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch, Chat, ChatTrigger } from "react-instantsearch";

const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <Chat agentId="8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9" />
      <ChatTrigger />
    </InstantSearch>
  );
}

Props

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" />

feedback · boolean

Whether to enable feedback (thumbs up/down) on assistant messages. Only available when using agentId.

JavaScript

<Chat
  agentId="8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9"
  feedback={true}
/>

requestOptions · object

Request options to send with the built-in Agent Studio completion requests. Use this option only with agentId. It isn’t available with a custom transport or custom chat instance.

The object accepts the following properties:

• queryParameters (Record<string, string | number | boolean>). Query parameters to append to each completion request.
• headers (Record<string, string> | Headers). Headers to send with each completion request.

InstantSearch always keeps compatibilityMode=ai-sdk-5, even if you set compatibilityMode in queryParameters. Custom headers can’t override the required Algolia identity headers (x-algolia-application-id, x-algolia-api-key) or the x-algolia-agent header that identifies InstantSearch. When users regenerate an assistant message, InstantSearch sends cache=false even if requestOptions.queryParameters.cache is true.

JavaScript

<Chat
  agentId="8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9"
  requestOptions={{
    queryParameters: {
      cache: false,
    },
    headers: {
      'X-Algolia-Secure-User-Token': 'ALGOLIA_SECURE_USER_TOKEN',
    },
  }}
/>

transport · HttpChatTransportInitOptions

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 · (nextUiState: object) => string

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

JavaScript

<Chat
  getSearchPageURL={(nextUiState) => {
    return `/search?${qs.stringify(nextUiState)}`;
  }}
/>

tools · Record<string, Tool>

An object defining the client-side tools that the agent can use to interact with your application. The object’s keys are tool names that must match the tools defined in the Agent Studio dashboard.

The widget has built-in renderers for search and Display Results tools. Import and use the exported constants as keys to customize the default rendering:

• SearchIndexToolType ('algolia_search_index'). Displays search results from an Algolia index in a carousel.
• DisplayResultsToolType ('algolia_display_results'). Displays grouped results from the tool’s streaming input in carousels.

JavaScript

import { DisplayResultsToolType, SearchIndexToolType } from 'react-instantsearch';

To customize only the appearance of each result in the built-in carousel, use the itemComponent prop instead. To replace the whole carousel layout, override the SearchIndexToolType tool’s layoutComponent. The tool result is on context.message.output (hits, nbHits, queryID):

JavaScript

<Chat
  agentId="YOUR_AGENT_ID"
  tools={{
    [SearchIndexToolType]: {
      layoutComponent: ({ context }) => {
        const items = context.message.output?.hits || [];

        return (
          <div className="MyCarousel">
            {items.map((item) => (
              <article className="MyCarousel-item" key={item.objectID}>
                <img src={item.image} alt={item.name} />
                <h3>{item.name}</h3>
                <span>${item.price}</span>
              </article>
            ))}
          </div>
        );
      },
    },
  }}
/>

For a step-by-step walkthrough, see Customize the chat results carousel.

Each tool is an object with the following properties:

• layoutComponent. A React component that renders the tool call in the chat. It receives a single context prop holding the tool’s own data alongside the shared chat state:

  • context.message. The tool call message. It contains input (parameters from the agent) and output (the result you provide with addToolResult). For more information about the message structure, see the Vercel AI SDK documentation.
  • context.records. The records the chat’s tools have fetched during the conversation, keyed by objectID. A tool that receives only object IDs reads the full record with context.records.get(objectID) rather than searching for it again. It also provides has(objectID) and getAll().
  • context.indexUiState. The current InstantSearch UI state.
  • context.setIndexUiState. Updates the InstantSearch UI state (for example, to refine filters or update the query based on the tool call).
  • context.applyFilters. Applies filters to the InstantSearch UI state from the tool call.
  • context.addToolResult. Sends the tool’s output back to the agent. Call this at least once before the next message. For more information, see the Vercel AI SDK documentation.
  • context.onClose. Dismisses the tool’s UI in the chat.
  • context.sendEvent. Sends click or conversion events related to the tool call. For more information, see the insights middleware documentation.
  • context also carries the shared chat state available to actionsComponent, emptyComponent, loaderComponent, and messagesErrorComponent, such as messages, status, and stop.

  The root-level props, such as message and addToolResult, are deprecated. The widget also passes them alongside context so components written for earlier API versions keep working. Read these props from context instead.

• cancelOutput. Optional function that returns the output to report when the chat starts a new message while the tool call is waiting for a result. For example, a confirmation prompt can return { confirmed: false }. The function receives { toolCallId, input }. If you don’t provide it, the chat reports the tool call as failed. This only changes the output reported to the agent. The tool continues waiting locally, so you can still submit a result later.

• onToolCall. Optional handler invoked when the agent calls the tool. Receives a parameter object with:

  • input. The parameters the agent passed to the tool.
  • addToolResult. Sends the tool’s output back to the agent. For more information, see the Vercel AI SDK documentation.
  • toolCallId. The unique identifier of the tool call.
  • toolName. The name of the tool being invoked.
  • dynamic. Whether the tool is dynamically registered.

• streamInput. Optional boolean. When true, the default loader is suppressed as the tool’s input is streamed from the agent. Use the partial input in your layout template to render the streaming state as input chunks arrive.

• shouldRender. Optional function that decides whether this tool call renders at all. It receives the chat context, plus message (the tool call under consideration) and parentMessage (the chat message it belongs to). Returning false skips the tool call and keeps the loader visible, so a tool can step aside for another one that renders in the same turn. When you omit it, the tool always renders. Overriding a built-in tool’s layoutComponent keeps that tool’s own shouldRender unless you pass your own.

• matchesToolName. Optional function that claims the tool names your agent’s server derives from this tool. It receives the incoming tool name and returns true when this tool handles it, for example matchesToolName: (toolName) => toolName.startsWith('my_tool_'). <Chat> first looks for a tool registered under the exact name and only then asks the other tools whether they claim it, so a claim never shadows another registration. When you omit it, the tool only handles calls sent under its own key. The built-in SearchIndexToolType tool already claims the index-suffixed names the Algolia MCP Server exposes, such as algolia_search_index_products.

JavaScript

<Chat tools={{
  addToCart: {
    layoutComponent: ({ context }) => <div>
      <p>Add {context.message.input.objectID} to the cart?</p>
      <button onClick={async () => {
        // add the product to the cart
        await addProductToCart(context.message.input.objectID);
        // notify the agent that the tool has been used
        context.addToolResult({
          output: {
            text: `added ${context.message.input.objectID} to cart`,
            done: true,
          },
        });
      }}>Add to cart</button>
    </div>,
    // if the shopper sends a new message before answering, tell the agent
    // the item wasn't added rather than reporting a failure
    cancelOutput: () => ({ text: "not added to cart", done: false }),
    onToolCall: ({ addToolResult }) => addToolResult({ output: {} }),
  },
  viewProduct: {
    layoutComponent: ({ context }) => {
      if (!context.message.output) {
        return <span>Loading product...</span>;
      }

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

}} />;

context · Record<string, string> | () => Record<string, string>

Extra context to send with each user message (for example, the current page or selected locale). The widget sends this context with every message, but doesn’t show it in the chat UI.

context can be a static object or a function that returns an object at send time. The widget attaches it to the latest user message as metadata.turnContext, following the Agent Studio per-turn context contract. The context never appears as a chat bubble.

The context must be a flat object that maps strings to strings (up to 32 keys, 4,096 bytes total). Agent Studio validates the payload and rejects malformed contexts. For details, see Per-turn context.

The widget sends context to the agent in plain text. Don’t put secrets, access tokens, or personally identifiable information you don’t intend to share with the model in this field.

Static object

<Chat
  agentId="YOUR_AGENT_ID"
  context={{ locale: "en", currentPage: "/products" }}
/>

initialMessages · UIMessage[]

Messages to pre-populate the chat with when it’s initialized. These messages are added without triggering an AI response.

initialMessages only applies when the chat doesn’t have any existing messages. When resume is enabled, initialMessages is ignored.

JavaScript

<Chat
  agentId="YOUR_AGENT_ID"
  initialMessages={[
    {
      id: "welcome",
      role: "assistant",
      parts: [{ type: "text", text: "Hi! How can I help you today?" }],
    },
  ]}
/>

initialUserMessage · string

A message to send automatically when the chat is initialized.

initialUserMessage is only sent when the chat doesn’t have any existing messages. It’s sent after initialMessages are applied. When resume is enabled, this message isn’t sent.

JavaScript

<Chat
  agentId="YOUR_AGENT_ID"
  initialUserMessage="Show me a few popular products to get started."
/>

resume · boolean · default: false

Whether to resume an ongoing chat generation stream when the widget mounts. Use this when restoring a chat session after a page reload to continue receiving an in-flight assistant response.

JavaScript

<Chat agentId="YOUR_AGENT_ID" resume />

persistence · boolean | { messages?: boolean; open?: boolean } · default: true

Whether to persist and restore the conversation and the open state of the chat panel from sessionStorage. When true (the default), the widget saves both the messages and whether the panel is open, and restores them when the widget re-mounts (for example, after a page reload). Set it to false to keep everything in memory only, so it’s cleared when the page reloads.

To control each policy separately, pass an object with the messages and open booleans. Only what you set to true is persisted:

• Omitted or true: persists the messages and the open state.
• false or {}: persists nothing.
• { messages: true }: persists the messages, but always starts with the panel closed.
• { open: true }: persists the open state, but doesn’t persist messages.

With a custom chat instance, the instance owns message persistence, so only the open option is available. The open state is persisted by default: pass { open: false } to opt out.

Changing the props of <Chat> rebuilds its internal chat instance, which drops the open state and any messages that persistence doesn’t cover. Keep prop references stable, especially functions, or pass your own chat instance to keep the conversation. In development, the widget warns when a prop change is about to discard state.

Disable persistence

<Chat agentId="YOUR_AGENT_ID" persistence={false} />

disableTriggerValidation · boolean · default: false

Whether to skip the validation that requires a way to open the chat. By default, <Chat> logs a development warning unless the chat has an entry point: a <ChatTrigger> widget, AI mode on a SearchBox or autocomplete, or an inline layout. Set this to true when you open the chat programmatically and don’t render any of those.

JavaScript

<Chat agentId="YOUR_AGENT_ID" disableTriggerValidation />

onFinish · (options: { message, messages, isAbort, isDisconnect, isError }) => void

A callback called when the assistant response has finished streaming, including when the stream is aborted, disconnected, or fails.

The callback receives an object with:

• message: the final assistant message.
• messages: the full message list including the new message.
• isAbort: true if the stream was stopped with stop().
• isDisconnect: true if the connection was lost.
• isError: true if the stream finished with an error.

JavaScript

<Chat
  agentId="YOUR_AGENT_ID"
  onFinish={({ message, isAbort, isError }) => {
    if (isError) {
      console.error("Chat stream failed", message);
      return;
    }
    if (!isAbort) {
      analytics.track("chat_message_completed", { messageId: message.id });
    }
  }}
/>

sendAutomaticallyWhen · (options: { messages: UIMessage[] }) => boolean | Promise<boolean>

A function that decides whether to resubmit the conversation to the agent without user input. It receives an object with messages, the current message list, and returns a boolean or a promise that resolves to one. When it returns true, <Chat> sends the conversation again so the agent can continue its turn.

By default, <Chat> uses lastAssistantMessageIsCompleteWithToolCalls. It returns true when the last step of the last assistant message has at least one client-side tool call, and every one of those calls has an output or an error. This is what lets the agent act on the results of your tools and keep answering. The function ignores tool calls the agent executes on its own side, because their results don’t come from your app.

<Chat> evaluates the function only for a response with at least one required client-side tool call. It waits for the response to finish streaming and for every required client-side tool call in that response to have a result, whichever comes last. It evaluates each response at most once, and skips a stream that’s stopped or fails.

Return false to stop <Chat> from continuing turns on its own, for example when your tools end the turn and users send the next message.

With a custom chat instance, set sendAutomaticallyWhen on the instance instead.

Never continue automatically

<Chat agentId="YOUR_AGENT_ID" sendAutomaticallyWhen={() => false} />

requiresSearch · boolean · default: true

Whether the widget makes InstantSearch require a main search request. By default (true), the widget contributes to the main search. Set it to false to opt the widget out of the main search: if it’s the only widget on the page, no main search request is sent.

JavaScript

<Chat agentId="YOUR_AGENT_ID" requiresSearch={false} />

showReasoning · boolean · default: true

Whether to display the reasoning an agent sends. Each assistant message shows its reasoning as a single collapsed disclosure. Expanding it lists the reasoning steps in the order they arrived, and while reasoning is in progress the collapsed row shows the latest step. The reader’s expanded or collapsed choice persists for the rest of the turn.

Set it to false to hide reasoning in this widget. It also hides a custom reasoningComponent.

This prop can’t make an agent send reasoning. Whether reasoning reaches the browser depends on the agent’s own sendReasoning setting, which is off by default.

Copied assistant messages include the answer text, not the reasoning.

JavaScript

<Chat agentId="YOUR_AGENT_ID" showReasoning={false} />

loaderPosition · string · default: "messages-end"

Where the loader appears while a chat turn is in progress.

• messages-end. Renders the loader in its own row after the last message.
• message-inline. Renders the loader inside the streaming assistant message, after the content received so far. Before the first assistant part arrives, the loader appears in its own row.

JavaScript

<Chat agentId="YOUR_AGENT_ID" loaderPosition="message-inline" />

To place the loader elsewhere in the chat panel, use CSS. See Control when and where the chat loader shows.

shouldShowLoader · (context) => boolean

Controls when the loader appears. The function receives the loader context and defaultValue, which indicates whether the widget would show the loader by default. The timing options still apply to the returned value.

Relevant context properties include:

• status. The current chat status: 'ready', 'submitted', 'streaming', or 'error'.
• phase. The current phase of the turn: 'submitted', 'tool', 'reasoning', or 'thinking'.
• message. The assistant message associated with the loader, when available.
• messages. The full conversation.
• tools. The tools available to the agent.
• defaultValue. Whether the widget would show the loader by default.

JavaScript

<Chat
  agentId="YOUR_AGENT_ID"
  shouldShowLoader={({ phase, defaultValue }) => phase === "tool" || defaultValue}
/>

loaderShowDelay · number · default: 250

The delay, in milliseconds, before the loader reappears after being hidden earlier in the same turn. The first loader in a turn isn’t delayed. Set this option to 0 to show the loader immediately after loading starts.

JavaScript

<Chat agentId="YOUR_AGENT_ID" loaderShowDelay={400} />

loaderMinDuration · number · default: 200

The minimum time, in milliseconds, that the loader remains visible while the turn is running. This prevents the loader from briefly appearing and disappearing. The loader hides immediately after the turn ends.

JavaScript

<Chat agentId="YOUR_AGENT_ID" loaderMinDuration={300} />

emptyComponent · (props: ChatComponentPropsWithContext<ChatEmptyProps>) => JSX.Element

A component to customize the welcome screen shown before the first message, when the chat doesn’t have any messages yet. Use it to display a greeting and starter prompts that send a message when clicked. It receives context, the supported API for shared chat state and callbacks:

• context.sendMessage. Sends a message to the agent. Call it with { text } to submit a starter prompt as the first message.
• context.status. The current chat status.
• context.onClose. Dismisses the chat.
• context.setInput. Sets the value of the prompt input without sending it.

The deprecated root-level sendMessage, status, onClose, and setInput props are also passed for compatibility. Read these values from context.

JavaScript

import { Chat } from "react-instantsearch";

function WelcomeScreen({ context }) {
  const prompts = ["What are your best-selling shoes?", "Show me new arrivals"];

  return (
    <div className="ais-ChatGreeting">
      <h2>How can I help you today?</h2>
      <div className="ais-ChatPromptSuggestions">
        {prompts.map((prompt) => (
          <button key={prompt} onClick={() => context.sendMessage({ text: prompt })}>
            {prompt}
          </button>
        ))}
      </div>
    </div>
  );
}

<Chat agentId="YOUR_CHAT_AGENT_ID" emptyComponent={WelcomeScreen} />;

To render the default greeting (heading, subheading, and an optional banner) inside your component, use the exported ChatGreeting component from react-instantsearch.

For a step-by-step walkthrough, see Show starter prompts on the chat welcome screen.

layoutComponent · (props: ChatLayoutOwnProps) => JSX.Element

A component to customize the overall layout of the chat widget. Use ChatInlineLayout for an inline (non-overlay) layout, ChatSidePanelLayout for a side panel on the right side of the page, or ChatOverlayLayout for the default floating overlay. To display a custom welcome screen before the first message, see Show starter prompts on the chat welcome screen.

Use the side panel layout to keep the chat widget beside your page content on wider screens. Unlike the inline layout, the side panel requires an entry point to open the widget.

By default, ChatSidePanelLayout adjusts document.body. Set its parentElement prop to a CSS selector to adjust another element.

• When the side panel opens, the layout adds the value of --ais-chat-width to the selected element’s inline margin-right.
• When the side panel closes, the layout restores the previous inline margin.
• On wider screens, maximizing the chat widget changes the panel width to --ais-chat-maximized-width without increasing the reserved margin, so the maximized panel can overlap page content.

At viewport widths of 680px or less, the side panel fills the viewport. This breakpoint is based on the viewport width, not the width of parentElement.

JavaScript

import { Chat, ChatSidePanelLayout } from "react-instantsearch";

function SidePanelLayout(props) {
  return (
    <ChatSidePanelLayout
      {...props}
      parentElement="#main-content"
    />
  );
}

<Chat
  agentId="8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9"
  layoutComponent={SidePanelLayout}
/>

loaderComponent · (props) => JSX.Element

A component to customize the loader shown while waiting for an AI response. Import the built-in ChatMessageLoader component from react-instantsearch to render the default loader, or provide your own component.

The component receives:

• translations. The resolved loader translations.
• context. The same context as shouldShowLoader, without defaultValue.
• inline. Whether the loader renders inside an assistant message instead of in its own row. It’s true when loaderPosition is message-inline and an assistant message is available.

JavaScript

import { Chat, ChatMessageLoader } from "react-instantsearch";

<Chat
  agentId="8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9"
  loaderComponent={(props) => (
    <ChatMessageLoader
      {...props}
      translations={{ loaderText: "Thinking..." }}
    />
  )}
/>

To replace the loading state, see Customize the chat loader.

reasoningComponent · (props: ChatMessageReasoningComponentProps) => JSX.Element

A component that renders the reasoning of an assistant message. It replaces the built-in disclosure. Unlike the built-in disclosure, which groups the whole message into one row, this component renders once per reasoning part, at that part’s own position in the stream.

The component receives:

• part. The reasoning part to render. Its text property holds the reasoning text.
• partIndex. The index of the reasoning part in the message’s parts array.
• isStreaming. Whether this reasoning part is still being produced.
• message. The message the reasoning part belongs to.
• context. The shared chat state, such as messages, status, and tools.

The component changes how reasoning renders, not whether it renders: showReasoning={false} hides this component along with the built-in disclosure.

JavaScript

<Chat
  agentId="YOUR_AGENT_ID"
  reasoningComponent={({ part, isStreaming }) => (
    <p className="MyReasoning" data-streaming={isStreaming}>
      {part.text}
    </p>
  )}
/>

components props · () => JSX.Element

Components to customize the rendering of the widget.

actionsComponent, emptyComponent, loaderComponent, and messagesErrorComponent receive a context prop that groups the current chat state and callbacks. The other components use the props described below.

• context.messages, context.status, context.error, context.activePart. The conversation and where it stands. For the status values, see Status values.
• context.open, context.maximized, context.isClearing. Panel state, for conditional rendering.
• context.tools. The tools registered for the assistant.
• context.sendMessage, context.regenerate, context.stop, context.setInput. Drive the conversation from a custom control.
• context.onReload, context.onNewConversation, context.onClose. Regenerate a message, clear the conversation, or close the panel.

JavaScript

<Chat
  messagesErrorComponent={({ context, errorMessage }) => (
    <p data-chat-status={context.status}>{errorMessage}</p>
  )}
/>

• itemComponent. Custom component for each result. Receives an object containing a single record.
• headerCloseIconComponent. Header: close icon component.
• headerMaximizeIconComponent. Header: maximize icon component. Receives a prop containing { maximized: boolean } for conditional rendering.
• headerMinimizeIconComponent. Header: minimize icon component.
• headerTitleIconComponent. Header: title icon component (defaults to sparkles).
• messagesErrorComponent. Messages: custom error component. Guardrail fallback responses render as assistant messages, not through this component. By default, the widget shows a generic message (Sorry, we are not able to generate a response at the moment. Please contact support.) and a “Start a new conversation” button that clears the conversation. The component receives:
  • errorMessage. The raw error message from the API or transport layer.
  • onNewConversation. Callback that clears the conversation and starts a new one. Use it to render a “Start a new conversation” action for errors where retrying fails again.
• assistantMessageLeadingComponent. Assistant message: custom leading component, such as an avatar.
• assistantMessageFooterComponent. Assistant message: custom footer component.
• userMessageLeadingComponent. User message: custom leading component, such as an avatar.
• userMessageFooterComponent. User message: custom footer component.
• promptFooterComponent. Prompt: custom footer component.
• promptHeaderComponent. Prompt: custom header component.
• suggestionsComponent. Custom component to render follow-up prompt suggestions. Receives a prop containing { suggestions: string[], onSuggestionClick: (str: string) => void }.

To customize the button that opens the chat, use the <ChatTrigger> widget’s toggleIconComponent prop instead.

To add a disclaimer or policy notice, see Add a legal notice to the chat widget.

JavaScript

<Chat
  // ...
  headerTitleIconComponent={() => <span>✨</span>}
  headerMaximizeIconComponent={({ maximized }) => (
    <span>{maximized ? "🔽" : "🔼"}</span>
  )}
  promptFooterComponent={() => (
    <a href="https://example.com/privacy-policy">Privacy policy</a>
  )}
/>

messagesProps · object

Props forwarded to the messages section of the widget. Use assistantMessageProps and userMessageProps to customize each role separately:

• textComponent. A component that renders each text part of the message. It replaces the default markdown rendering. It receives:
  • part. The text part to render. Its text property holds the text content.
  • message. The message the text part belongs to.
  • messages. The full conversation, when available.
  • status. The current chat status: 'ready', 'submitted', 'streaming', or 'error'.
  • partIndex. The index of the text part in the message’s parts array.
• parseMarkdown. The default value is true. The widget renders text and reasoning parts as Markdown, including links, code blocks, and emphasis. Set parseMarkdown to false to render reasoning parts and text parts that use the default renderer as plain text. Line breaks are preserved and links aren’t clickable. Use this option for user messages when Markdown characters such as * or _ should remain literal. If you provide a textComponent, it takes precedence for text parts. parseMarkdown then only controls reasoning parts.

JavaScript

<Chat
  // ...
  messagesProps={{
    assistantMessageProps: {
      textComponent: ({ part, status }) => (
        <span className="MyAssistantText" data-status={status}>
          {part.text}
        </span>
      ),
    },
    userMessageProps: {
      textComponent: ({ part }) => (
        <span className="MyUserText">{part.text}</span>
      ),
    },
  }}
/>

To render user messages as plain text while keeping the default Markdown rendering for assistant messages:

JavaScript

<Chat
  // ...
  messagesProps={{
    userMessageProps: {
      parseMarkdown: false,
    },
  }}
/>

classNames · Partial<ChatClassNames>

The CSS classes you can override and pass to the widget’s elements. It’s useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.

• 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, such as an avatar.
  • content. The content element.
  • message. The message text element.
  • reasoning. The reasoning disclosure.
  • reasoningHeader. The reasoning disclosure header.
  • reasoningIcon. The reasoning icon.
  • reasoningLabel. The reasoning label.
  • reasoningChevron. The reasoning disclosure chevron.
  • reasoningBody. The reasoning body.
  • reasoningText. The reasoning text.
  • 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 text area element.

JavaScript

<Chat
  classNames={{
    root: "MyCustomChat",
    container: "MyCustomChatContainer MyCustomChatContainer--subclass",
    header: {
      root: "MyCustomChatHeader",
      title: ["MyCustomChatHeaderTitle", "MyCustomChatHeaderTitle--subclass"],
      // ...
    },
    // ...
  }}
/>

translations · Partial<ChatTranslations>

A dictionary of translations to customize the UI text and support internationalization.

• header. The header section of the widget.
  • clearLabel. Accessible label for the clear button.
  • closeLabel. Accessible label for the close button.
  • maximizeLabel. Accessible label for the maximize button.
  • minimizeLabel. Accessible label for the minimize button.
  • title. Title to display.
• messages. The messages section of the widget.
  • copyToClipboardLabel. Accessible label for the copy to clipboard action.
  • feedbackThankYouText. Text shown after feedback is submitted (default: 'Thanks for your feedback!').
  • loaderText. Text to display in the loader. Pass a function to customize the text based on the turn context, for example ({ phase }) => phase === 'tool' ? 'Searching...' : 'Thinking...'.
  • regenerateLabel. Accessible label for the regenerate action.
  • scrollToBottomLabel. Accessible label for the scroll to bottom button.
  • sendingFeedbackLabel. Accessible label for the feedback spinner (default: 'Sending feedback...').
  • thumbsDownLabel. Accessible label for the thumbs down button (default: 'Dislike').
  • thumbsUpLabel. Accessible label for the thumbs up button (default: 'Like').
• message. Individual message in the messages section.
  • messageLabel. Accessible label for the message.
  • actionsLabel. Accessible label for the actions container.
  • reasoningLabel. Label for a reasoning disclosure.
• prompt. The prompt section of the widget.
  • disclaimer. Disclaimer text shown in the prompt footer.
  • emptyMessageTooltip. The tooltip for the submit button when message is empty.
  • sendMessageTooltip. The tooltip for the send button.
  • stopResponseTooltip. The tooltip for the stop button.
  • textareaLabel. Accessible label for the text area.
  • textareaPlaceholder. Placeholder text for the text area.

To add richer prompt or message notices, see Add a legal notice to the chat widget.

JavaScript

<Chat
  translations={{
    header: {
      title: "My AI shopping assistant",
      closeLabel: "Close chat",
      // ...
    },
    // ...
  }}
/>

...props · React.ComponentProps<'div'>

Any <div> prop to forward to the root element of the widget.

JavaScript

<Chat className="MyCustomChat" title="My custom title" />

Streaming and resumption

Assistant responses stream over Server-Sent Events. The useChat hook exposes the streaming lifecycle if you want to drive a custom UI.

Status values

useChat returns a status value, which can be one of:

• 'ready'. The chat is idle and ready to accept a new message.
• 'submitted'. A user message was submitted and the assistant hasn’t started responding yet.
• 'streaming'. The assistant is streaming a response.
• 'error'. The last response finished with an error. Call clearError() before sending a new message.

Each message part also carries a state of 'streaming' or 'done' while the response streams.

Stop and resume

useChat also returns:

• stop(). Aborts the current streaming response. The onFinish callback runs with isAbort: true.
• resumeStream(). Reconnects to an in-flight stream. Call this on mount, or pass resume to <Chat> to do it automatically.

JavaScript

import { useChat } from "react-instantsearch";

function StopButton() {
  const { status, stop } = useChat({ agentId: "YOUR_AGENT_ID" });

  if (status !== "streaming") {
    return null;
  }

  return <button onClick={() => stop()}>Stop</button>;
}

To resume an ongoing stream after a reload, set resume on <Chat>, or call resumeStream() from a custom component.