Customize the chat results carousel

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

When the agent searches your index, the Chat widget renders the results in a built-in carousel. If your agent uses the Grouped Results tool, the widget renders each group of curated results in its own built-in carousel. You can customize the search results carousel at three levels, from the least to the most involved:

Restyle the default carousel with CSS.
Change the markup of each result card with the itemComponent prop.
Replace the entire carousel layout by overriding the search tool.

Restyle the default carousel with CSS

If the default structure works and you only want a different look, target the carousel’s CSS classes. The search results carousel uses classes prefixed with ais-ChatToolSearchIndexCarousel (for example, ais-ChatToolSearchIndexCarouselHeader). See the styling guide for the full approach.

Customize each result card

Use the itemComponent prop to change what each card in the carousel looks like. The same component renders cards in search results, recommendations, and in carousels created by the Grouped Results tool. It receives a single record:

React

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

const searchClient = algoliasearch(
  "ALGOLIA_APPLICATION_ID",
  "ALGOLIA_SEARCH_ONLY_API_KEY"
);

function ProductCard({ item }) {
  return (
    <article className="product-card">
      <img src={item.image} alt={item.name} />
      <h3>{item.name}</h3>
      <span className="product-card-price">${item.price}</span>
    </article>
  );
}

function App() {
  return (
    <InstantSearch searchClient={searchClient}>
      <Chat agentId="YOUR_AGENT_ID" itemComponent={ProductCard} />
    </InstantSearch>
  );
}

Set the card’s image source to the appropriate image attribute in your records. If you restrict the attributes returned by the Algolia Search tool, include the image attribute in your attributesToRetrieve. For most stores, this is enough: you swap in your own product-card markup and the carousel behavior (header, scroll buttons, “View all”) stays as-is.

Replace the entire carousel layout

To change more than the cards—such as the header, the scroll controls, or the wrapper—override the tool that renders the carousel. Import the tool type and use it as a key in the tools prop:

SearchIndexToolType renders the search results carousel.
RecommendToolType renders the recommendations carousel.
GroupedResultsToolType renders the grouped results carousels. This tool builds its carousels from the streaming tool input instead of message.output, so the following example doesn’t apply to it. For more information, see tools.

All of them are exported from react-instantsearch. Whatever you pass under a tool key fully replaces the built-in rendering for that tool.

React

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

function ResultsCarousel({ message, sendEvent }) {
  const items = message.output?.hits || [];

  if (items.length === 0) {
    return <p>No results found.</p>;
  }

  return (
    <div className="MyCarousel">
      <div className="MyCarousel-header">
        {items.length} of {message.output?.nbHits} results
      </div>
      <div className="MyCarousel-track">
        {items.map((item) => (
          <article
            className="MyCarousel-item"
            key={item.objectID}
            onClick={() => sendEvent("click", item, "Product clicked from chat")}
          >
            <img src={item.image} alt={item.name} />
            <h3>{item.name}</h3>
            <span>${item.price}</span>
          </article>
        ))}
      </div>
    </div>
  );
}

function App() {
  return (
    <Chat
      agentId="YOUR_AGENT_ID"
      tools={{
        [SearchIndexToolType]: {
          layoutComponent: ResultsCarousel,
        },
      }}
    />
  );
}

The layoutComponent receives:

message. The tool call message. The result is on message.output (hits, nbHits, queryID). The agent’s parameters are on message.input.
sendEvent. Sends click or conversion events for the result, using the insights middleware.
applyFilters and onClose. Apply filters to the InstantSearch UI state, or dismiss the tool’s UI.

Overriding a tool changes only how the result is displayed in the chat. The tool itself—its name, when the agent calls it, and its parameters—is configured on the agent in the Agent Studio dashboard.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Customize the chat results carousel

Restyle the default carousel with CSS

Customize each result card

Replace the entire carousel layout

​Restyle the default carousel with CSS

​Customize each result card

​Replace the entire carousel layout

​Related

Restyle the default carousel with CSS

Customize each result card

Replace the entire carousel layout

Related