PromptSuggestions

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

For more information, see Agent Studio.

Signature

<PromptSuggestions
  configurationId={string}
  // Required prop, either one of
  agentId={string}
  transport={object}
  // Optional props
  context={object | function}
  transformHits={function}
  transformItems={function}
  onSuggestionClick={function}
  layoutComponent={function}
  headerComponent={function | false}
  classNames={object}
  translations={object}

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

Import

JavaScript

import { PromptSuggestions } from "react-instantsearch";

Use <PromptSuggestions> to display AI-generated prompt suggestions as clickable pills. An Agent Studio agent generates the suggestions from the current search context: the query, the active filters, and a sample of the results. When users click a suggestion, the widget opens the <Chat> widget on the same index and submits the prompt. The widget fetches suggestions when it mounts, and fetches them again when the query, filters, or results change. Suggestions stream in progressively, and a skeleton placeholder shows while the first suggestions load. These suggestions differ from the follow-up prompt suggestions that appear after each agent response inside the chat. See also: Agent Studio

The default click behavior needs a <Chat> widget on the same index. Without one, the widget logs a development warning when users click a suggestion. To handle clicks yourself, use onSuggestionClick.

Examples

JavaScript

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

const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <PromptSuggestions
        agentId="8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9"
        configurationId="CONFIGURATION_ID"
      />
      <Chat agentId="8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9" />
    </InstantSearch>
  );
}

Props

string

required

The identifier of the prompt configuration that generates the suggestions. Create prompt configurations in the Components section of your agent in the Agent Studio dashboard.

JavaScript

<PromptSuggestions
  agentId="8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9"
  configurationId="CONFIGURATION_ID"
/>

string

The unique identifier of the agent to connect to. You can find the agentId in the Agent Studio dashboard. Required unless you provide a custom transport.

JavaScript

<PromptSuggestions
  agentId="8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9"
  configurationId="CONFIGURATION_ID"
/>

object

A custom transport object to handle the communication between the widget and your own backend. When set, agentId and the search client credentials are ignored.The object accepts the following properties:

api (string). The endpoint URL to send suggestion requests to.
headers (Record<string, string>). Headers to send with each request.
prepareSendMessagesRequest (function). Transforms the request body before it’s sent. Receives the body object and returns { body }.

JavaScript

<PromptSuggestions
  configurationId="CONFIGURATION_ID"
  transport={{
    api: "https://api.example.com/api/v1/suggestions",
    headers: {
      "X-Api-Version": "2025-01-01",
    },
  }}
/>

object | () => object

Explicit page context to send to the agent instead of the automatically extracted search context.By default, the widget sends the current query, the active filters, and a sample of the results. Set context to replace this with your own data, for example the product record on a product detail page. context can be a static object or a function that returns an object for each fetch.When you set context, the widget fetches suggestions even without search results, and transformHits is ignored.

The widget sends context to the agent in plain text. Don’t put secrets, access tokens, or personally identifiable information you don’t intend to share with the model in this field.

<PromptSuggestions
  agentId="AGENT_ID"
  configurationId="CONFIGURATION_ID"
  context={{
    productName: "Wireless headphones",
    category: "Audio",
    price: 99,
  }}
/>

<PromptSuggestions
  agentId="AGENT_ID"
  configurationId="CONFIGURATION_ID"
  context={() => ({
    currentPage: window.location.pathname,
  })}
/>

(hits: Hit[]) => unknown[]

A function that receives the current results and returns the subset (or reshaped objects) sent to the agent as context. By default, the widget sends the first five hits with internal metadata (attributes prefixed with _) removed. This prop is ignored when you set context.

JavaScript

<PromptSuggestions
  agentId="AGENT_ID"
  configurationId="CONFIGURATION_ID"
  transformHits={(hits) =>
    hits.slice(0, 3).map((hit) => ({
      name: hit.name,
      brand: hit.brand,
      price: hit.price,
    }))
  }
/>

(items: string[], metadata: { query, results }) => string[]

A function that receives the generated suggestions and returns the list to display. The second argument contains the current query and results.

JavaScript

<PromptSuggestions
  agentId="AGENT_ID"
  configurationId="CONFIGURATION_ID"
  transformItems={(items) => items.slice(0, 2)}
/>

(prompt: string, helpers: { sendToChat }) => void

A function to override the default click behavior (sending the prompt to the chat widget). It receives the clicked prompt and a helpers object with sendToChat, so you can run custom logic (for example, analytics) and then fall through to the default behavior.

JavaScript

<PromptSuggestions
  agentId="AGENT_ID"
  configurationId="CONFIGURATION_ID"
  onSuggestionClick={(prompt, { sendToChat }) => {
    analytics.track("suggestion_clicked", { prompt });
    sendToChat(prompt);
  }}
/>

(props) => JSX.Element

A component to replace the default pills layout with custom markup. The component owns the full rendering: the list, the loading state, and the click handlers. It receives:

suggestions. The generated prompt strings.
isLoading. Whether the widget is fetching suggestions.
onSuggestionClick. The click handler for a suggestion.
isChatBusy. Whether the chat widget is streaming a response.

JavaScript

<PromptSuggestions
  agentId="AGENT_ID"
  configurationId="CONFIGURATION_ID"
  layoutComponent={({ suggestions, isLoading, onSuggestionClick, isChatBusy }) => {
    if (isLoading) {
      return <span>Generating suggestions...</span>;
    }

    return (
      <ul>
        {suggestions.map((suggestion) => (
          <li key={suggestion}>
            <button
              disabled={isChatBusy}
              onClick={() => onSuggestionClick(suggestion)}
            >
              {suggestion}
            </button>
          </li>
        ))}
      </ul>
    );
  }}
/>

(props) => JSX.Element | false

A component to replace the default header. Set it to false to hide the header. It receives the classNames and translations objects.

JavaScript

<PromptSuggestions
  agentId="AGENT_ID"
  configurationId="CONFIGURATION_ID"
  headerComponent={({ translations }) => <h4>{translations.headerTitle}</h4>}
/>

Partial<PromptSuggestionsClassNames>

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.
header. The header element.
headerTitle. The header title element.
suggestion. Each suggestion pill.
skeleton. The skeleton container shown while loading.
skeletonItem. Each skeleton placeholder pill.

JavaScript

<PromptSuggestions
  agentId="AGENT_ID"
  configurationId="CONFIGURATION_ID"
  classNames={{
    root: "MyCustomPromptSuggestions",
    suggestion: [
      "MyCustomPromptSuggestionsPill",
      "MyCustomPromptSuggestionsPill--subclass",
    ],
  }}
/>

Partial<PromptSuggestionsTranslations>

A dictionary of translations to customize the UI text and support internationalization.

headerTitle. The title displayed in the header.

JavaScript

<PromptSuggestions
  agentId="AGENT_ID"
  configurationId="CONFIGURATION_ID"
  translations={{
    headerTitle: "Ask about these results",
  }}
/>

React.ComponentProps<'div'>

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

JavaScript

<PromptSuggestions
  agentId="AGENT_ID"
  configurationId="CONFIGURATION_ID"
  className="MyCustomPromptSuggestions"
/>

Hook

Use the usePromptSuggestions Hook to build a fully custom UI. It accepts the same connector props (agentId or transport, configurationId, context, transformHits, transformItems) and returns:

suggestions (string[]). The generated prompt strings.
isLoading (boolean). Whether the widget is fetching suggestions.
onSuggestionClick ((prompt: string) => void). The default click handler, which sends the prompt to the chat.
sendToChat ((prompt: string) => boolean). Sends the prompt to the <Chat> widget on the same index, with the page context attached as per-turn context. Returns true if the chat received it.
refresh (() => void). Fetches new suggestions for the current search state.
isChatBusy (boolean). Whether the chat widget is streaming a response. Use it to set the disabled attribute on your suggestion buttons.

JavaScript

import { usePromptSuggestions } from "react-instantsearch";

function CustomPromptSuggestions() {
  const { suggestions, isLoading, onSuggestionClick, refresh, isChatBusy } =
    usePromptSuggestions({
      agentId: "8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9",
      configurationId: "CONFIGURATION_ID",
    });

  if (isLoading) {
    return <span>Generating suggestions...</span>;
  }

  return (
    <div>
      {suggestions.map((suggestion) => (
        <button
          key={suggestion}
          disabled={isChatBusy}
          onClick={() => onSuggestionClick(suggestion)}
        >
          {suggestion}
        </button>
      ))}
      <button onClick={() => refresh()}>Refresh</button>
    </div>
  );
}

React InstantSearch

PromptSuggestions

Import

About this widget

Examples

Props

Hook

​Import

​About this widget

​Examples

​Props

​Hook

Import

About this widget

Examples

Props

Hook