chatTrigger

Renders a button that opens the chat widget’s overlay, built with Algolia Agent Studio.

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

For more information, see Agent Studio.

Signature

chatTrigger({
  container: string | HTMLElement,
  // Optional parameters
  floating?: boolean,
  templates?: object,
  cssClasses?: object,
});

Import

Package manager

import { chatTrigger } from 'instantsearch.js/es/widgets';

About this widget

Use the chatTrigger widget to render 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.

The chat widget 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

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

chatTrigger({
  container: '#chat-trigger',
});

Options

container · string | HTMLElement · required

The CSS Selector or HTMLElement to insert the widget into.

string

chatTrigger({
  container: '#chat-trigger',
});

floating · 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,
});

templates · object

The templates to customize parts of the widget.

• layout. Template for the trigger button layout. Receives the button props, including open, onClick, and toggleIconComponent.
• icon. Template for the trigger button icon. Receives a parameter containing { isOpen: boolean } for conditional rendering.

JavaScript

chatTrigger({
  // ...
  templates: {
    icon({ isOpen }, { html }) {
      return html`<span>${isOpen ? '×' : '✨'}</span>`;
    },
  },
});

cssClasses · object

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.

• button. CSS class to add to the button.

JavaScript

chatTrigger({
  // ...
  cssClasses: {
    button: 'MyCustomChatTrigger',
  },
});

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.

Customize the UI with connectChatTrigger

If you want to create your own UI of the chatTrigger widget, you can use connectors.

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 the chatTrigger widget, so the chat widget’s entry-point validation counts them and you don’t need to also add chatTrigger.

To use connectChatTrigger, you can import it with the declaration relevant to how you installed InstantSearch.js.

Package manager

import { connectChatTrigger } from "instantsearch.js/es/connectors";

Then it’s a 3-step process:

JavaScript

// 1. Create a render function
const renderChatTrigger = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customChatTrigger = connectChatTrigger(renderChatTrigger);

// 3. Instantiate
search.addWidgets([customChatTrigger()]);

Create a render function

This rendering function is called before the first search (init lifecycle step) and each time results come back from Algolia (render lifecycle step).

JavaScript

const renderChatTrigger = (renderOptions, isFirstRender) => {
  const { open, toggleOpen, openChat, isChatBusy } = renderOptions;

  if (isFirstRender) {
    // Do some initial rendering and bind events
  }

  // Update the rendering with the new state
};

Render options

open · boolean

Whether the chat panel is open.

toggleOpen · () => void

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

openChat · (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 object of string values attached to the outgoing message, which grounds the answer in the page the shopper triggered it from. The context option on the chat widget takes precedence when it’s set.

isChatBusy · 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.

Create and instantiate the custom widget

First, create your custom widgets using a rendering function. Then, instantiate them with parameters.

You can pass two kinds of parameters:

• Instance parameters. Predefined options that configure Algolia’s behavior.
• Custom parameters. Parameters you define to make the widget reusable and adaptable.

Inside the renderFunction, both instance and custom parameters are accessible through connector.widgetParams.

JavaScript

const customChatTrigger = connectChatTrigger(renderChatTrigger);

search.addWidgets([customChatTrigger()]);

Instance options

connectChatTrigger doesn’t take any instance options, so pass anything your render function needs through a closure.

Full example

JavaScript

import { connectChatTrigger } from "instantsearch.js/es/connectors";

function createAskButton({ container, product }) {
  const button = document.createElement("button");
  button.textContent = "Ask about this product";
  container.appendChild(button);

  return (renderOptions) => {
    const { openChat, isChatBusy } = renderOptions;

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

const customChatTrigger = connectChatTrigger(
  createAskButton({
    container: document.querySelector("#ask-about-product"),
    product,
  })
);

search.addWidgets([customChatTrigger()]);