promptSuggestions

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

For more information, see Agent Studio.

Signature

promptSuggestions({
  container: string | HTMLElement,
  configurationId: string,
  // Required parameter, either one of
  agentId?: string,
  transport?: object,
  // Optional parameters
  context?: object | function,
  transformHits?: function,
  transformItems?: function,
  onSuggestionClick?: function,
  templates?: object,
  cssClasses?: object,
  translations?: object,
});

Import

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

const { promptSuggestions } = instantsearch.widgets;

Use the promptSuggestions widget 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

promptSuggestions({
  container: '#prompt-suggestions',
  agentId: '8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9',
  configurationId: 'CONFIGURATION_ID',
});

chat({
  container: '#chat',
  agentId: '8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9',
});

Options

string | HTMLElement

required

The CSS Selector or HTMLElement to insert the widget into.

promptSuggestions({
  container: '#prompt-suggestions',
});

promptSuggestions({
  container: document.querySelector('#prompt-suggestions'),
});

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({
  // ...
  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',
});

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({
  // ...
  transport: {
    api: 'https://api.example.com/api/v1/suggestions',
    headers: {
      'X-Api-Version': '2025-01-01',
    },
  },
});

object | function

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({
  // ...
  context: {
    productName: 'Wireless headphones',
    category: 'Audio',
    price: 99,
  },
});

promptSuggestions({
  // ...
  context: () => ({
    currentPage: window.location.pathname,
  }),
});

function

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 option is ignored when you set context.

JavaScript

promptSuggestions({
  // ...
  transformHits: (hits) =>
    hits.slice(0, 3).map((hit) => ({
      name: hit.name,
      brand: hit.brand,
      price: hit.price,
    })),
});

function

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

JavaScript

promptSuggestions({
  // ...
  transformItems: (items, { query }) =>
    items.slice(0, 2).map((item) => item.toUpperCase()),
});

function

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({
  // ...
  onSuggestionClick: (prompt, { sendToChat }) => {
    analytics.track('suggestion_clicked', { prompt });
    sendToChat(prompt);
  },
});

object

The templates to use for the widget.

JavaScript

promptSuggestions({
  // ...
  templates: {
    // ...
  },
});

object

The CSS classes you can override:

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({
  // ...
  cssClasses: {
    root: 'MyCustomPromptSuggestions',
    suggestion: [
      'MyCustomPromptSuggestionsPill',
      'MyCustomPromptSuggestionsPill--subclass',
    ],
  },
});

object

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

headerTitle. The title displayed in the header.

JavaScript

promptSuggestions({
  // ...
  translations: {
    headerTitle: 'Ask about these results',
  },
});

Templates

You can customize parts of a widget’s UI using the Templates API. Each template includes an html function, which you can use as a tagged template. This function safely renders templates as HTML strings and works directly in the browser—no build step required. For details, see Templating your UI.

The html function is available in InstantSearch.js version 4.46.0 or later.

function

A template to replace the default pills layout with custom markup. The template 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({
  // ...
  templates: {
    layout({ suggestions, isLoading, onSuggestionClick, isChatBusy }, { html }) {
      if (isLoading) {
        return html`<span>Generating suggestions...</span>`;
      }

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

function | false

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

JavaScript

promptSuggestions({
  // ...
  templates: {
    header({ translations }, { html }) {
      return html`<h4>${translations.headerTitle}</h4>`;
    },
  },
});

HTML output

HTML

<div class="ais-PromptSuggestions">
  <div class="ais-PromptSuggestions-header">
    <span class="ais-PromptSuggestions-headerTitle">Suggestions</span>
  </div>
  <button class="ais-Button ais-Button--primary ais-Button--sm ais-PromptSuggestions-suggestion">
    What are the best headphones under $100?
  </button>
  <button class="ais-Button ais-Button--primary ais-Button--sm ais-PromptSuggestions-suggestion">
    Which of these have noise cancellation?
  </button>
</div>

While the first suggestions load, the widget renders skeleton placeholders instead of the pills:

HTML

<div class="ais-PromptSuggestions">
  <div class="ais-PromptSuggestions-skeleton">
    <div class="ais-PromptSuggestions-skeletonItem"></div>
    <div class="ais-PromptSuggestions-skeletonItem"></div>
    <div class="ais-PromptSuggestions-skeletonItem"></div>
  </div>
</div>

Connector render state

Use connectPromptSuggestions to build a fully custom UI. Its render state exposes:

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 { connectPromptSuggestions } from 'instantsearch.js/es/connectors';

const renderPromptSuggestions = (renderOptions, isFirstRender) => {
  const { suggestions, isLoading, onSuggestionClick, isChatBusy } = renderOptions;
  const container = document.querySelector('#prompt-suggestions');

  if (isLoading) {
    container.textContent = 'Generating suggestions...';
    return;
  }

  container.innerHTML = '';
  suggestions.forEach((suggestion) => {
    const button = document.createElement('button');
    button.textContent = suggestion;
    button.disabled = isChatBusy;
    button.addEventListener('click', () => onSuggestionClick(suggestion));
    container.appendChild(button);
  });
};

const customPromptSuggestions = connectPromptSuggestions(
  renderPromptSuggestions,
);

search.addWidgets([
  customPromptSuggestions({
    agentId: '8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9',
    configurationId: 'CONFIGURATION_ID',
  }),
]);

​Import

​About this widget

​Examples

​Options

​Templates

​HTML output

​Connector render state

Import

About this widget

Examples

Options

Templates

HTML output

Connector render state