> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# PromptSuggestions
> Displays AI-generated prompt suggestions for the current page, built with Algolia Agent Studio.
export const customLabel_0 = undefined
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
This widget is **{customLabel_0 || "experimental"}** and is subject to change in minor versions.
For more information, see [Agent Studio](/doc/guides/algolia-ai/agent-studio).
```tsx Signature expandable theme={"system"}
}
/>
```
## Import
```jsx JavaScript icon=code theme={"system"}
import { PromptSuggestions } from "react-instantsearch";
```
## About this widget
Use `` 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 [``](/doc/api-reference/widgets/chat/react) 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](/doc/guides/algolia-ai/agent-studio/how-to/agent-configuration#follow-up-prompt-suggestions) that appear after each agent response inside the chat.
See also: [Agent Studio](/doc/guides/algolia-ai/agent-studio)
The default click behavior needs a [``](/doc/api-reference/widgets/chat/react) widget on the same index. Without one, the widget logs a development warning when users click a suggestion. To handle clicks yourself, use [`onSuggestionClick`](#param-on-suggestion-click).
## Examples
```jsx JavaScript icon=code expandable theme={"system"}
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 (
);
}
```
## Props
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.
```jsx JavaScript icon=code theme={"system"}
```
The unique identifier of the agent to connect to. You can find the `agentId` in the [Agent Studio dashboard](https://dashboard.algolia.com/generativeAi/agent-studio/agents). Required unless you provide a custom [`transport`](#param-transport).
```jsx JavaScript icon=code theme={"system"}
```
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`). Headers to send with each request.
* `prepareSendMessagesRequest` (`function`). Transforms the request body before it's sent. Receives the body object and returns `{ body }`.
```jsx JavaScript icon=code theme={"system"}
```
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.
```jsx Static object theme={"system"}
```
```jsx Function theme={"system"}
({
currentPage: window.location.pathname,
})}
/>
```
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`](#param-context).
```jsx JavaScript icon=code theme={"system"}
hits.slice(0, 3).map((hit) => ({
name: hit.name,
brand: hit.brand,
price: hit.price,
}))
}
/>
```
A function that receives the generated suggestions and returns the list to display.
The second argument contains the current `query` and `results`.
```jsx JavaScript icon=code theme={"system"}
items.slice(0, 2)}
/>
```
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.
```jsx JavaScript icon=code theme={"system"}
{
analytics.track("suggestion_clicked", { prompt });
sendToChat(prompt);
}}
/>
```
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.
```jsx JavaScript icon=code expandable theme={"system"}
{
if (isLoading) {
return Generating suggestions...;
}
return (
{suggestions.map((suggestion) => (
))}
);
}}
/>
```
A component to replace the default header. Set it to `false` to hide the header. It receives the `classNames` and `translations` objects.
```jsx JavaScript icon=code theme={"system"}
{translations.headerTitle}
}
/>
```
The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/react#style-your-widgets) and pass to the widget's elements.
It's useful to style widgets with class-based CSS frameworks like [Bootstrap](https://getbootstrap.com) or [Tailwind CSS](https://tailwindcss.com).
* `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.
```jsx JavaScript icon=code theme={"system"}
```
A dictionary of translations to customize the UI text and support internationalization.
* `headerTitle`. The title displayed in the header.
```jsx JavaScript icon=code theme={"system"}
```
Any `
` prop to forward to the root element of the widget.
```jsx JavaScript icon=code theme={"system"}
```
## 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 `` widget on the same index, with the page context attached as [per-turn context](/doc/guides/algolia-ai/agent-studio/how-to/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.
```jsx JavaScript icon=code expandable theme={"system"}
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 Generating suggestions...;
}
return (