PromptSuggestions

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

For more information, see Agent Studio.

Signature

<PromptSuggestions
  // Required prop, either one of
  agentId={string}
  transport={object}
  // Optional props
  configurationId={string}
  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. If a change produces the same context as the last request, the widget sends nothing and keeps the suggestions already on screen. 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" />
      <Chat agentId="8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9" />
    </InstantSearch>
  );
}

Props

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" />

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 }.

The widget sends a POST request with a JSON body of { task, kind, input }, where task is the configurationId if you set one, kind is prompt_suggestions, and input is the page context. It also appends stream=true to the endpoint URL.Answer with the suggestions nested under output:

Response

{
  "output": {
    "suggestions": [
      "Which of these has the longest battery life?",
      "Compare the two cheapest models"
    ]
  }
}

Send that document as application/json to render the suggestions once the request completes, or stream it as text/plain to render each suggestion as it arrives.

JavaScript

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

string

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. For more information, see Generate prompt suggestions for your pages.When you omit configurationId, the widget uses the enabled prompt suggestions configuration of the agent. Set it to target a specific configuration, for example when the agent has several of them.

JavaScript

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

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.A static object doesn’t depend on the search state, so the widget fetches once and then keeps those suggestions instead of fetching again. A failed request is the exception: the next search state change retries it. To fetch again, return changing values from a context function, or call refresh from the Hook.

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"
  context={{
    productName: "Wireless headphones",
    category: "Audio",
    price: 99,
  }}
/>

<PromptSuggestions
  agentId="AGENT_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"
  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"
  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"
  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, the error state, and the click handlers. It receives:

suggestions. The generated prompt strings.
isLoading. Whether the widget is fetching suggestions.
error. The Error thrown by the latest request, or undefined. When a request fails, suggestions is empty. The default layout renders nothing in that case, so use this component to show an error state.
onSuggestionClick. The click handler for a suggestion.
isChatBusy. Whether the chat widget is streaming a response.

JavaScript

<PromptSuggestions
  agentId="AGENT_ID"
  layoutComponent={({
    suggestions,
    isLoading,
    error,
    onSuggestionClick,
    isChatBusy,
  }) => {
    if (error) {
      return <span>Suggestions are unavailable.</span>;
    }

    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"
  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"
  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"
  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"
  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.
error (Error | undefined). The error thrown by the latest suggestions request. When a request fails, suggestions is empty. The error clears when the query, filters, or results change, and when you call refresh.
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, even when the context is unchanged. It does nothing while a request is in flight, or before the first search results arrive.
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",
    });

  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