ChatTrigger - Algolia

For more information, see Agent Studio.

Signature

<ChatTrigger
  // Optional props
  floating={boolean}
  onClick={function}
  classNames={object}
  translations={object}
  // Optional component props
  toggleIconComponent={function}

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

Import

JavaScript

import { ChatTrigger } from "react-instantsearch";

See this widget in action

Preview this widget and its behavior.

ChatTrigger renders a button that opens the Chat widget’s overlay. By default, it’s a floating action button anchored to the bottom-right of the viewport. Chat doesn’t render a way to open it on its own, so pair it with ChatTrigger unless you provide another entry point such as AI mode on a SearchBox or an inline layout. See also: Agent Studio

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

boolean

default:true

Whether to render the button as a floating action button anchored to the bottom-right of the viewport. Set it to false to render an inline button that flows with surrounding content.

JavaScript

<ChatTrigger floating={false} />

() => void

A callback that runs when users click the trigger, alongside opening or closing the chat.

JavaScript

<ChatTrigger
  onClick={() => {
    analytics.track("chat_trigger_clicked");
  }}
/>

(props: { isOpen: boolean }) => JSX.Element

A component to replace the default icon. It receives a prop containing { isOpen: boolean } for conditional rendering—for example, to show a different icon when the chat is open.

JavaScript

<ChatTrigger
  toggleIconComponent={({ isOpen }) => <span>{isOpen ? "×" : "✨"}</span>}
/>

Partial<ChatToggleButtonClassNames>

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 (the button).

JavaScript

<ChatTrigger
  classNames={{
    root: "MyCustomChatTrigger",
  }}
/>

Partial<ChatToggleButtonTranslations>

A dictionary of translations to customize the button’s accessible label, which screen readers announce.

openLabel (string). The accessible label when the chat isn’t open. The default is Open chat.
closeLabel (string). The accessible label when the chat is open. The default is Close chat.

JavaScript

<ChatTrigger
  translations={{
    openLabel: "Ouvrir le chat",
    closeLabel: "Fermer le chat",
  }}
/>

React.ComponentProps<'button'>

Any button prop to forward to the root element of the widget. An aria-label you pass this way replaces the labels from translations in both states.

JavaScript

<ChatTrigger className="MyCustomChatTrigger" id="chat-trigger" />

HTML output

HTML

<button
  class="ais-ChatToggleButton ais-ChatToggleButton--floating"
  aria-label="Open chat"
>
  <!-- icon -->
</button>

When the chat is open, the button also gets the ais-ChatToggleButton--open class, and its aria-label becomes Close chat.

Hook

React InstantSearch lets you create your own UI for the ChatTrigger widget with useChatTrigger. Hooks provide APIs to access the widget state and interact with InstantSearch. The useChatTrigger Hook doesn’t take any parameters and returns APIs. Use it inside the InstantSearch component, alongside a Chat widget. Use it for entry points the built-in button doesn’t cover: a hero call to action, a keyboard shortcut, or an “ask about this product” link. They all go through the same connector as ChatTrigger, so the chat widget’s entry-point validation counts them and you don’t need to also render ChatTrigger.

Usage

First, create your React component:

JavaScript

import { useChatTrigger } from "react-instantsearch";

function CustomChatTrigger() {
  const { open, toggleOpen, openChat, isChatBusy } = useChatTrigger();

  return <>{/*Your JSX*/}</>;
}

Then, render the widget:

JavaScript

<CustomChatTrigger />;

Parameters

Hooks accept parameters. You can either pass them manually or forward props from a custom component.

When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders. Use useCallback() to keep function references stable. You don’t need to do this for arrays and objects.

useChatTrigger doesn’t take any parameters.

APIs

Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch.

boolean

Whether the chat panel is open.

() => void

Opens the chat panel when it’s closed, and closes it when it’s open.

(options?: OpenChatOptions) => boolean

Opens the chat panel, and submits a message to it when you pass one. Returns true when it submitted a message.Without a message, it opens the panel and focuses its input. With a message, it submits the message unless the chat is already busy, so check isChatBusy before you call it.options accepts:

message. Text to submit as a user message. Empty or whitespace-only values open the chat without sending anything.
referer. Identifies the request’s entry point in the x-algolia-referer header. Values include 'ai-mode', 'compare', 'prompt-suggestions-widget', 'prompt-suggestions-autocomplete', and 'result-card'. Pass your own string for a custom entry point.
turnContext. Provides context about the page where the user opened the chat. Pass a Record<string, string> object. The widget attaches this object to the outgoing message and merges it with the Chat widget’s context prop, if configured. If both objects define the same property, the widget uses the value from turnContext.

boolean

Whether the chat is submitting or streaming a message, and so can’t accept a new one. It’s false until the chat has initialized.

Example

JavaScript

import { useChatTrigger } from "react-instantsearch";

function AskAboutProduct({ product }) {
  const { openChat, isChatBusy } = useChatTrigger();

  return (
    <button
      disabled={isChatBusy}
      onClick={() =>
        openChat({
          message: `Tell me more about ${product.name}`,
          referer: "product-detail-page",
          turnContext: { objectID: product.objectID },
        })
      }
    >
      Ask about this product
    </button>
  );
}

​Import

See this widget in action

​About this widget

​Examples

​Props

​HTML output

​Hook

​Usage

​Parameters

​APIs

​Example

Import

About this widget

Examples

Props

HTML output

Hook

Usage

Parameters

APIs

Example