FilterSuggestions

Displays relevant facet filter suggestions powered by Algolia AI Agents.

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

Signature

<FilterSuggestions
  // Required prop, either one of
  agentId={string}
  transport={object}
  // Optional props
  attributes={string[]}
  maxSuggestions={number}
  debounceMs={number}
  hitsToSample={number}
  transformItems={(items) => items}
  itemComponent={(props) => JSX.Element}
  headerComponent={(props) => JSX.Element | false}
  emptyComponent={(props) => JSX.Element}
  classNames={object}
  ...props={ComponentProps<'div'>}
/>

Import

JavaScript

import { FilterSuggestions } from 'react-instantsearch';

About this widget

Use the <FilterSuggestions /> widget to display relevant facet filter suggestions powered by Algolia AI agents. Suggestions are based on the current search query, refinements, and context. Clicking a suggestion applies the corresponding filter.

See also: Algolia AI Agents

To create this agent, choose the Filter suggestions template in the Agent Studio dashboard. The model used should be a faster, cheaper one (for example gpt-4.1-mini), as suggestions don’t require deep reasoning.

Example

JavaScript

import React from 'react';
import {
  InstantSearch,
  FilterSuggestions,
  RefinementList,
  Hits,
  SearchBox,
} from 'react-instantsearch';

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <SearchBox />
      <FilterSuggestions agentId="YOUR_AGENT_ID" />
      <RefinementList attribute="brand" />
      <Hits />
    </InstantSearch>
  );
}

Props

agentId · string

The unique identifier of the agent to connect to. You can find the agentId in the Agent Studio dashboard.

JavaScript

<FilterSuggestions agentId="YOUR_AGENT_ID" />

transport · object

A custom transport object to handle the communication between the widget and the agent. The API endpoint must be compatible with Vercel AI SDK 5.

JavaScript

<FilterSuggestions
  transport={{
    api: 'https://api.example.com/agent',
    headers: {
      'X-Agent-Id': 'YOUR_AGENT_ID',
    },
  }}
/>

attributes · string[]

Restrict suggestions to these facet attributes.

JavaScript

<FilterSuggestions attributes={['brand', 'category']} />

maxSuggestions · number

Maximum number of suggestions to display. Default: 3.

debounceMs · number

Debounce delay before fetching suggestions, in milliseconds. Default: 300.

hitsToSample · number

Number of hits to send for context. Default: 5.

transformItems · function

Transform the suggestions before rendering.

JavaScript

<FilterSuggestions
  transformItems={(items) =>
    items.map((item) => ({ ...item, label: item.label.toUpperCase() }))
  }
/>

itemComponent · (props) => JSX.Element

Custom component to render each suggestion.

JavaScript

<FilterSuggestions
  itemComponent={({ suggestion, refine }) => (
    <button onClick={() => refine(suggestion.attribute, suggestion.value)}>
      {suggestion.label} ({suggestion.count})
    </button>
  )}
/>

headerComponent · (props) => JSX.Element | false

Custom or disable header.

JavaScript

<FilterSuggestions headerComponent={false} />

emptyComponent · (props) => JSX.Element

Custom component for empty state.

JavaScript

<FilterSuggestions emptyComponent={() => <div>No suggestions</div>} />

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

• root: The root element of the widget.
• loadingRoot: The root element when loading.
• emptyRoot: The root element when empty.
• header: The header section.
• headerIcon: The sparkles icon in the header.
• headerTitle: The title text in the header.
• skeleton: The skeleton container when loading.
• skeletonItem: Each skeleton placeholder item.
• list: The list of suggestions.
• item: Each suggestion item.
• button: The button for each suggestion.
• label: The label text for each suggestion.
• count: The count for each suggestion.

JavaScript

<FilterSuggestions
  classNames={{
    root: 'MyCustomFilterSuggestions',
    item: 'MyCustomFilterSuggestionsItem',
    button: 'MyCustomButton',
  }}
/>

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

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

JavaScript

<FilterSuggestions
  className="MyCustomFilterSuggestions"
  title="My custom title"
/>

See also

• Algolia AI agents
• RefinementList widget