ChatTrigger - Algolia

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

For more information, see Agent Studio.

Signature

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

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

Import

JavaScript

import { ChatTrigger } from "react-instantsearch";

<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 called when the trigger is clicked, in addition to 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",
  }}
/>

React.ComponentProps<'button'>

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

JavaScript

<ChatTrigger className="MyCustomChatTrigger" aria-label="Open chat" />

HTML output

HTML

<button class="ais-ChatToggleButton ais-ChatToggleButton--floating">
  <!-- icon -->
</button>

When the chat is open, the button also gets the ais-ChatToggleButton--open class.

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 takes no parameters and returns APIs. It must be used 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() for memoization. Arrays and objects are automatically memoized.

useChatTrigger takes no 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. The entry point the request came from, sent as the x-algolia-referer header so the backend can attribute the traffic. The built-in values are 'ai-mode', 'prompt-suggestions-widget', and 'prompt-suggestions-autocomplete'. Pass your own string for a custom entry point.
turnContext. A flat Record<string, string> of page context attached to the outgoing message, which grounds the answer in the page the shopper triggered it from. The context prop on <Chat> takes precedence when it’s set.

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

​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