filterSuggestions

Displays relevant facet filter suggestions powered by Algolia AI Agents.

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

Signature

filterSuggestions({
  container: string | HTMLElement,
  // Required parameter, either one of
  agentId?: string,
  transport?: object,
  // Optional parameters
  attributes?: string[],
  maxSuggestions?: number,
  debounceMs?: number,
  hitsToSample?: number,
  transformItems?: function,
  templates?: object,
  cssClasses?: object,
})

Import

Package manager

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

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.

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

filterSuggestions({
  container: '#filter-suggestions',
  agentId: 'YOUR_AGENT_ID',
  attributes: ['brand'],
  maxSuggestions: 5,
  templates: {
    item({ suggestion, refine }, { html }) {
      return html`<button onClick=${refine}>
        ${suggestion.label} (${suggestion.count})
      </button>`;
    },
    header: false,
  },
});

Options

container · string | HTMLElement · required

The CSS Selector or HTMLElement to insert the widget into.

string

filterSuggestions({
  container: '#filter-suggestions',
});

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) {
    return items.map((item) => ({ ...item, label: item.label.toUpperCase() }));
  },
});

templates · object

Custom templates for rendering:

• item: function to render each suggestion.
• header: function or false to customize or disable header.
• empty: function to render when there are no suggestions.

JavaScript

filterSuggestions({
  // ...
  templates: {
    item({ suggestion, refine }, { html }) {
      return html`<button onClick=${refine}>${suggestion.label}</button>`;
    },
    header: false,
    empty() {
      return '<div>No suggestions</div>';
    },
  },
});

cssClasses · object

The CSS classes you can override:

• 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({
  // ...
  cssClasses: {
    root: 'MyCustomFilterSuggestions',
    item: 'MyCustomFilterSuggestionsItem',
    button: 'MyCustomButton',
  },
});

See also

• Algolia AI agents
• refinementList widget