> ## Documentation Index
> Fetch the complete documentation index at: https://www.algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# resultCard
> Displays an AI Overview card above the results with an Agent Studio recommendation based on the query and the top hits.
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).
```ts Signature theme={"system"}
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
```js Package manager theme={"system"}
import { resultCard } from 'instantsearch.js/es/widgets';
```
```js CDN theme={"system"}
const { resultCard } = instantsearch.widgets;
```
## About this widget
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](/doc/guides/algolia-ai/agent-studio/how-to/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](/doc/guides/managing-results/rules/rules-overview) 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](#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`](/doc/api-reference/widgets/chat/js) 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](/doc/api-reference/widgets/chat/js#param-disable-trigger-validation) for the chat, so a page with both doesn't also need a [`chatTrigger`](/doc/api-reference/widgets/chat-trigger/js) 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](/doc/api-reference/api-parameters/ruleContexts) `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`](/doc/api-reference/api-parameters/renderingContent) in its search parameters:
```json JSON icon=braces theme={"system"}
{
"renderingContent": {
"widgets": {
"resultCard": {
"enabled": true
}
}
}
}
```
## Examples
```js JavaScript icon=code theme={"system"}
resultCard({
container: '#result-card',
agentId: 'AGENT_ID',
});
chat({
container: '#chat',
agentId: 'AGENT_ID',
});
```
## Options
The CSS Selector or `HTMLElement` to insert the widget into.
```js string theme={"system"}
resultCard({
container: '#result-card',
});
```
```js HTMLElement theme={"system"}
resultCard({
container: document.querySelector('#result-card'),
});
```
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).
It's required even with a custom [`transport`](#param-transport), because the widget derives its rule context from it.
The card only hands its conversation to a `chat` widget with the same `agentId`.
```js JavaScript icon=code theme={"system"}
resultCard({
// ...
agentId: 'AGENT_ID',
});
```
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`](/doc/api-reference/widgets/chat/js#param-transport) option of the `chat` widget.
You can't use it together with [`requestOptions`](#param-request-options).
```js JavaScript icon=code theme={"system"}
resultCard({
// ...
transport: {
api: 'https://chatapi.example.com/api/v1/chat',
},
});
```
Request options to send with the built-in Agent Studio completion requests.
You can't use it together with [`transport`](#param-transport).
The object accepts the following properties:
* `queryParameters` (`Record`). Query parameters to append to each completion request.
* `headers` (`Record | Headers`). Headers to send with each completion request.
```js JavaScript icon=code theme={"system"}
resultCard({
// ...
requestOptions: {
headers: {
'X-Session-Id': 'SESSION_ID',
},
},
});
```
The [templates](#templates) to use for the widget.
```js JavaScript icon=code theme={"system"}
resultCard({
// ...
templates: {
// ...
},
});
```
The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#style-your-widgets):
* `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.
```js JavaScript icon=code theme={"system"}
resultCard({
// ...
cssClasses: {
root: 'MyCustomResultCard',
body: ['MyCustomResultCardBody', 'MyCustomResultCardBody--subclass'],
},
});
```
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"`.
```js JavaScript icon=code theme={"system"}
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates).
This function safely renders templates as HTML strings and works directly in the browser—no build step required.
For details, see [Templating your UI](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#templating-your-ui).
The `html` function is available in InstantSearch.js version 4.46.0 or later.
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](#connector-render-state).
```js JavaScript icon=code expandable theme={"system"}
resultCard({
// ...
templates: {
layout({ status, messages, error, retry }, { html }) {
if (status === 'hidden') {
return html``;
}
if (status === 'failed') {
return html`
${error ? error.message : 'Something went wrong.'}
`;
},
},
});
```
## HTML output
```html HTML icon=code-xml theme={"system"}
AI Overview
...
```
While the answer loads, the body holds a skeleton placeholder instead of the message:
```html HTML icon=code-xml theme={"system"}
```
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`](/doc/api-reference/widgets/insights/js) middleware.
The user message in `messages` contains the full question that the widget sends to the agent.
To display the query, use `query` instead.
```js JavaScript icon=code expandable theme={"system"}
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',
}),
]);
```