resultCard - Algolia

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

For more information, see Agent Studio.

Signature

resultCard({
  container: string | HTMLElement,
  agentId: string,
  // Optional parameters, at most one of
  transport?: object,
  requestOptions?: object,
  // Optional parameters
  templates?: object,
  cssClasses?: object,
  translations?: object,
});

Import

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

const { resultCard } = instantsearch.widgets;

Use the resultCard widget to display an “AI Overview” card above your results. The widget sends the query, the active filters, and the first five hits to an Agent Studio agent as per-turn context, and asks the agent which of these results it recommends and why. The answer streams into the card, and a skeleton placeholder shows until the first text arrives. The card only shows when the search meets both conditions:

A rule that matches the search sets renderingContent.widgets.resultCard.enabled to true in the search response. For more information, see Activate the card with a rule.
The query has at least two words.

The widget sends a new request only when the query, the filters, or the first five hits change. Going to another page of results doesn’t send a new request. Users can collapse the card to its header, which hides the answer, the follow-up suggestions, and the Continue in chat button. The answer keeps generating in the meantime, and the card stays collapsed for new searches until users restore it. The card clips long answers and shows a Show more button to reveal the full text. If the answer completes without any text, the card doesn’t render. When a chat widget with the same agentId is on the same index, the card shows a Continue in chat button and up to two follow-up suggestions from the agent. Both hand the card’s conversation to the chat and open it. A suggestion is also sent to the chat as the next message. If the chat is generating a response, the handoff doesn’t happen. That makes the widget an entry point for the chat, so a page with both doesn’t also need a chatTrigger widget. Without a matching chat widget, the card hides these actions and, in development, logs a warning.

Activate the card with a rule

The widget adds the rule context agent-studio-result-card-AGENT_ID to every search, where _ replaces any character in the agent ID other than letters, digits, _, and -. Use this context as a rule condition to limit the rule to searches that include the widget. To show the card, add a rule whose consequence sets renderingContent in its search parameters:

JSON

{
  "renderingContent": {
    "widgets": {
      "resultCard": {
        "enabled": true
      }
    }
  }
}

Examples

JavaScript

resultCard({
  container: '#result-card',
  agentId: 'AGENT_ID',
});

chat({
  container: '#chat',
  agentId: 'AGENT_ID',
});

Options

string | HTMLElement

required

The CSS Selector or HTMLElement to insert the widget into.

resultCard({
  container: '#result-card',
});

resultCard({
  container: document.querySelector('#result-card'),
});

string

required

The unique identifier of the agent to connect to. You can find the agentId in the Agent Studio dashboard. It’s required even with a custom transport, because the widget derives its rule context from it. The card only hands its conversation to a chat widget with the same agentId.

JavaScript

resultCard({
  // ...
  agentId: 'AGENT_ID',
});

object

A custom transport object to send the card’s requests to your own backend instead of Agent Studio. It has the same shape as the transport option of the chat widget. You can’t use it together with requestOptions.

JavaScript

resultCard({
  // ...
  transport: {
    api: 'https://chatapi.example.com/api/v1/chat',
  },
});

object

Request options to send with the built-in Agent Studio completion requests. You can’t use it together with transport.The object accepts the following properties:

queryParameters (Record<string, string | number | boolean>). Query parameters to append to each completion request.
headers (Record<string, string> | Headers). Headers to send with each completion request.

JavaScript

resultCard({
  // ...
  requestOptions: {
    headers: {
      'X-Session-Id': 'SESSION_ID',
    },
  },
});

object

The templates to use for the widget.

JavaScript

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

object

The CSS classes you can override:

root. The root element of the widget.
header. The header element.
headerTitle. The header title element.
continueButton. The Continue in chat button.
minimizeButton. The button that minimizes or maximizes the card.
body. The element that holds the answer and clips it.
loader. The skeleton placeholder shown while the answer loads.
message. Each answer message.
suggestions. The follow-up suggestions container.
expandButton. The button that shows or clips a long answer.

JavaScript

resultCard({
  // ...
  cssClasses: {
    root: 'MyCustomResultCard',
    body: ['MyCustomResultCardBody', 'MyCustomResultCardBody--subclass'],
  },
});

object

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

headerTitle. The title displayed in the header. Defaults to "AI Overview".
continueInChatText. The text of the button that hands the conversation to the chat. Defaults to "Continue in chat".
minimizeLabel. The accessible label of the button that minimizes the card. Defaults to "Minimize".
maximizeLabel. The accessible label of the button that maximizes a minimized card. Defaults to "Maximize".
expandText. The text of the button that shows a clipped answer in full. Defaults to "Show more".
collapseText. The text of the button that clips an expanded answer. Defaults to "Show less".
retryText. The text of the retry button shown when the request fails. Defaults to "Retry".

JavaScript

resultCard({
  // ...
  translations: {
    headerTitle: 'Our pick',
    continueInChatText: 'Ask a follow-up question',
  },
});

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 card with custom markup. The template owns the full rendering, including every status and the retry and handoff actions. It receives the same data as the connector render state.

JavaScript

resultCard({
  // ...
  templates: {
    layout({ status, messages, error, retry }, { html }) {
      if (status === 'hidden') {
        return html``;
      }

      if (status === 'failed') {
        return html`<div>
          <p>${error ? error.message : 'Something went wrong.'}</p>
          <button onClick=${retry}>Retry</button>
        </div>`;
      }

      const answer = messages
        .filter((message) => message.role === 'assistant')
        .flatMap((message) => message.parts)
        .filter((part) => part.type === 'text')
        .map((part) => part.text)
        .join('');

      return html`<section>
        <p>${answer || 'Loading...'}</p>
      </section>`;
    },
  },
});

HTML output

HTML

<section class="ais-ResultCard" data-status="complete" aria-live="polite">
  <div class="ais-ResultCard-header">
    <span class="ais-ResultCard-headerTitle">
      <svg>...</svg>
      AI Overview
    </span>
    <button class="ais-Button ais-Button--outline ais-Button--sm ais-ResultCard-continueButton">
      Continue in chat
    </button>
    <button class="ais-Button ais-Button--ghost ais-Button--sm ais-Button--icon-only ais-ResultCard-minimizeButton" title="Minimize" aria-label="Minimize" aria-expanded="true">
      <svg>...</svg>
    </button>
  </div>
  <div class="ais-ResultCard-body ais-ResultCard-body--clipped">
    <article class="ais-ChatMessage ais-ChatMessage--left ais-ChatMessage--subtle ais-ResultCard-message">...</article>
  </div>
  <button class="ais-Button ais-Button--ghost ais-Button--sm ais-ResultCard-expandButton" aria-expanded="false">
    Show more
    <svg>...</svg>
  </button>
</section>

While the answer loads, the body holds a skeleton placeholder instead of the message:

HTML

<div class="ais-ResultCard-body">
  <div class="ais-ResultCard-loader">
    <div class="ais-ResultCard-loaderLine"></div>
    <div class="ais-ResultCard-loaderLine"></div>
    <div class="ais-ResultCard-loaderLine"></div>
  </div>
</div>

When users collapse the card, the ais-ResultCard-minimizeButton button has aria-expanded="false" and the Maximize label, and the body, the expand button, the Continue in chat button, and the suggestions don’t render. When users expand a long answer, or when the request fails, the body has the ais-ResultCard-body--expanded class. When the answer is complete and isn’t clipped, the follow-up suggestions render after the body in a div with the ais-ChatPromptSuggestions ais-ResultCard-suggestions classes.

Connector render state

Use connectResultCard to build a fully custom UI. It accepts the same agentId, transport, and requestOptions options as the widget. Its render state exposes:

status ('hidden' | 'loading' | 'streaming' | 'complete' | 'failed'). The card status. It’s hidden when no rule enables the card or when the query is shorter than two words. It’s loading while the widget waits to send the request and until the response starts streaming.
query (string). The query the answer is about.
messages (UIMessage[]). The card’s conversation: the user message, then the assistant answer as it streams.
error (Error | undefined). The error of the latest failed request. It’s only set when status is failed.
suggestions (string[] | undefined). Follow-up suggestions sent by the agent with the answer.
retry (() => void). Sends the request again.
canContinueInChat (boolean). Whether a chat widget with the same agentId is on the same index.
continueInChat ((message?: string) => void). Hands the conversation to the chat widget and opens it. When you pass message, the chat sends it as the next message.
expanded (boolean). Whether a long answer shows in full instead of clipped.
setExpanded ((expanded: boolean) => void). Shows or clips a long answer.
sendEvent (function). Sends an event to the insights middleware.

The user message in messages contains the full question that the widget sends to the agent. To display the query, use query instead.

JavaScript

import { connectResultCard } from 'instantsearch.js/es/connectors';

const renderResultCard = (renderOptions, isFirstRender) => {
  const { status, messages, canContinueInChat, continueInChat } =
    renderOptions;
  const container = document.querySelector('#result-card');

  if (isFirstRender) {
    return;
  }

  if (status === 'hidden') {
    container.innerHTML = '';
    return;
  }

  const answer = messages
    .filter((message) => message.role === 'assistant')
    .flatMap((message) => message.parts)
    .filter((part) => part.type === 'text')
    .map((part) => part.text)
    .join('');

  container.innerHTML = '';

  const text = document.createElement('p');
  text.textContent = answer || 'Loading...';
  container.appendChild(text);

  if (status === 'complete' && canContinueInChat) {
    const continueButton = document.createElement('button');
    continueButton.textContent = 'Continue in chat';
    continueButton.addEventListener('click', () => continueInChat());
    container.appendChild(continueButton);
  }
};

const customResultCard = connectResultCard(renderResultCard);

search.addWidgets([
  customResultCard({
    agentId: 'AGENT_ID',
  }),
]);

​Import

​About this widget

​Activate the card with a rule

​Examples

​Options

​Templates

​HTML output

​Connector render state

Import

About this widget

Activate the card with a rule

Examples

Options

Templates

HTML output

Connector render state