ais-chat - Algolia

Signature

<ais-chat
  // Required. Choose one:
  agent-id="string"
  :transport="object"
  :chat="object"
  // Optional parameters (agent-id only)
  :feedback="boolean"
  :request-options="object"
  // Optional parameters
  :get-search-page-u-r-l="function"
  :tools="object"
  :context="object | function"
  :initial-messages="array"
  initial-user-message="string"
  :resume="boolean"
  :persistence="boolean | object"
  :disable-trigger-validation="boolean"
  :requires-search="boolean"
  :on-finish="function"
  :on-error="function"
  :on-data="function"
  :on-tool-call="function"
  title="string"
  layout="overlay | inline | sidePanel"
  :layout-props="object"
  :show-reasoning="boolean"
  loader-position="string"
  :should-show-loader="function"
  :loader-show-delay="number"
  :loader-min-duration="number"
  :header-props="object"
  :messages-props="object"
  :prompt-props="object"
  :class-names="object"
  :translations="object"
  // Optional component parameters
  :item-component="object | function"
  :layout-component="object | function"
  :header-component="object | function"
  :prompt-component="object | function"
  :suggestions-component="object | function"
  :empty-component="object | function"
  :loader-component="object | function"
  :actions-component="object | function"
  :messages-error-component="object | function"
  :reasoning-component="object | function"
  :prompt-header-component="object | function"
  :prompt-footer-component="object | function"
  :header-title-icon-component="object | function"
  :header-close-icon-component="object | function"
  :header-minimize-icon-component="object | function"
  :header-maximize-icon-component="object | function"
  :assistant-message-leading-component="object | function"
  :assistant-message-footer-component="object | function"
  :user-message-leading-component="object | function"
  :user-message-footer-component="object | function"
/>

Import

Component
Plugin

To ensure optimal bundle sizes, see Optimize build size.

Vue

import { AisChat, AisChatTrigger } from "vue-instantsearch";
// Use "vue-instantsearch/vue3/es" for Vue 3

export default {
  components: {
    AisChat,
    AisChatTrigger,
  },
  // ...
};

This imports all widgets, even the ones you don’t use. For more information, see Get started with Vue InstantSearch.

JavaScript

import Vue from "vue";
import InstantSearch from "vue-instantsearch";
// Use "vue-instantsearch/vue3/es" for Vue 3

Vue.use(InstantSearch);

Use ais-chat to add an AI chat interface to your Vue InstantSearch app. Connect it to an Algolia Agent Studio agent with agent-id, or provide a custom transport or chat instance. See also: Agent Studio

With the default overlay and the sidePanel layouts, ais-chat renders the chat panel but doesn’t provide a way to open it. Add the ais-chat-trigger widget to the same ais-instant-search instance, or use the inline layout. Otherwise, the widget logs a development warning. To silence it, set disable-trigger-validation to true.

Examples

Vue

<template>
  <ais-instant-search index-name="instant_search" :search-client="searchClient">
    <ais-chat agent-id="8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9">
      <template v-slot:item="{ item }">
        <article>
          <img :src="item.image" :alt="item.name" />
          <h2>{{ item.name }}</h2>
        </article>
      </template>
    </ais-chat>
    <ais-chat-trigger />
  </ais-instant-search>
</template>

<script>
  import { liteClient as algoliasearch } from "algoliasearch/lite";

  export default {
    data() {
      return {
        searchClient: algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_SEARCH_API_KEY"),
      };
    },
  };
</script>

Props

string

The unique identifier of the agent to connect to. You can find the agent ID in the Agent Studio dashboard.

Vue

<ais-chat agent-id="8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9" />

boolean

Whether to enable feedback (thumbs up/down) on assistant messages. Only available when using agent-id.

Vue

<ais-chat agent-id="8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9" :feedback="true" />

object

Request options to send with the built-in Agent Studio completion requests. Use this option only with agent-id. It isn’t available with a custom transport or custom chat instance.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.

InstantSearch always keeps compatibilityMode=ai-sdk-5, even if you set compatibilityMode in queryParameters. Custom headers can’t override the required Algolia identity headers (x-algolia-application-id, x-algolia-api-key) or the x-algolia-agent header that identifies InstantSearch.

Vue

<ais-chat
  agent-id="8f7c4a2d-3b1e-4d5f-9a6c-e2b1f5d0c3e9"
  :request-options="{
    queryParameters: { cache: false },
    headers: { 'X-Algolia-Secure-User-Token': 'ALGOLIA_SECURE_USER_TOKEN' },
  }"
/>

HttpChatTransportInitOptions

A custom transport object to handle the communication between the chat widget and the agent. The API endpoint must be compatible with Vercel AI SDK 5.

Vue

<ais-chat
  :transport="{
    api: 'https://chatapi.example.com/api/v1/chat',
    headers: { 'X-Api-Version': '2025-01-01' },
  }"
/>

Chat

A preconfigured chat instance. If you pass chat, configure its transport and message persistence on the instance.

Vue

<ais-chat :chat="chatInstance" />

(nextUiState: object) => string

A function to return the URL of the main search page with the nextUiState. The search tool’s View all link uses it to send users to the main search page.

Vue

<ais-chat
  // ...
  :get-search-page-u-r-l="(nextUiState) => `/search?${qs.stringify(nextUiState)}`"
/>

Record<string, Tool>

An object defining the client-side tools that the agent can use to interact with your application. The object’s keys are tool names that must match the tools defined in the Agent Studio dashboard.The widget has built-in renderers for the search, recommend, grouped results, and compare products tools. To customize the default rendering, use the tool name constants from instantsearch.js/es/lib/chat as keys:

SearchIndexToolType ('algolia_search_index'). Displays search results from an Algolia index in a carousel.
RecommendToolType ('algolia_recommend'). Displays recommendations in a carousel.
GroupedResultsToolType ('algolia_grouped_results'). Displays grouped results from the tool’s streaming input in carousels.
CompareProductsToolType ('algolia_compare_products'). Displays a comparison table of products.

To customize only the appearance of each result, use the item slot instead. To replace a whole tool layout, override the tool’s layoutComponent with a Vue component that accepts a context prop. Overriding a built-in tool’s layoutComponent keeps that tool’s streamInput and shouldRender options unless you pass your own.

Vue

<template>
  <ais-chat agent-id="YOUR_AGENT_ID" :tools="tools" />
</template>

<script>
  import { SearchIndexToolType } from "instantsearch.js/es/lib/chat";
  // MyCarousel.vue declares a `context` prop
  // and renders `context.message.output.hits`
  import MyCarousel from "./MyCarousel.vue";

  export default {
    data() {
      return {
        tools: {
          [SearchIndexToolType]: { layoutComponent: MyCarousel },
        },
      };
    },
  };
</script>

Each tool is an object with the following properties:

layoutComponent. A Vue component or render function that renders the tool call in the chat. It receives a single context prop holding the tool’s own data alongside the shared chat state:
- context.message. The tool call message. It contains input (parameters from the agent) and output (the result you provide with addToolResult).
- context.records. The records the chat’s tools have fetched during the conversation, keyed by objectID. Read a record with context.records.get(objectID).
- context.indexUiState. The current InstantSearch UI state.
- context.setIndexUiState. Updates the InstantSearch UI state.
- context.applyFilters. Applies filters to the InstantSearch UI state from the tool call.
- context.addToolResult. Sends the tool’s output back to the agent. Call this at least once before the next message.
- context.onClose. Dismisses the tool’s UI in the chat.
- context.sendEvent. Sends click or conversion events related to the tool call.
onToolCall. Optional handler invoked when the agent calls the tool. It receives input, addToolResult, signal, toolCallId, toolName, and dynamic. It can be async. When it throws or rejects, the chat settles the tool call as failed.
cancelOutput. Optional function that returns the output to report when the chat starts a new message while the tool call is waiting for a result.
timeout. Optional number of milliseconds for onToolCall to submit a result, 20000 by default. Set it to false to wait indefinitely.
retryOnError. Optional boolean, false by default. When true, a failed tool call shows a Retry button.
streamInput. Optional boolean. When true, the chat hides the default loader while the tool’s input streams from the agent.
shouldRender. Optional function that decides whether this tool call renders at all.
matchesToolName. Optional function that claims the tool names your agent’s server derives from this tool.

For more details about each property, see the React Chat reference.

Record<string, string> | () => Record<string, string>

Extra context to send with each user message (for example, the current page or selected locale). The widget sends this context with every message, but doesn’t show it in the chat UI.context can be a static object or a function that returns an object at send time. The widget attaches it to the latest user message as metadata.turnContext, following the Agent Studio per-turn context contract. The context must be a flat object that maps strings to strings (up to 32 keys, 4,096 bytes total).

The agent can read the values you send in context. Don’t include secrets, access tokens, or personal information unless you intend to share them with the model.

Vue

<ais-chat
  agent-id="YOUR_AGENT_ID"
  :context="{ locale: 'en', currentPage: '/products' }"
/>

UIMessage[]

Messages to pre-populate the chat with when it initializes. The widget adds these messages without triggering an AI response.initial-messages only applies when the chat doesn’t have any existing messages. When you enable resume, the widget ignores initial-messages.

Vue

<ais-chat
  agent-id="YOUR_AGENT_ID"
  :initial-messages="[
    {
      id: 'welcome',
      role: 'assistant',
      parts: [{ type: 'text', text: 'Hi! How can I help you today?' }],
    },
  ]"
/>

string

A message to send automatically when the chat initializes.The widget only sends initial-user-message when the chat doesn’t have any existing messages. It sends it after applying initial-messages. When you enable resume, the widget doesn’t send this message.

Vue

<ais-chat
  agent-id="YOUR_AGENT_ID"
  initial-user-message="Show me a few popular products to get started."
/>

boolean

default:false

Whether to resume an ongoing chat generation stream when the widget mounts. Use this when restoring a chat session after a page reload to continue receiving an in-flight assistant response.

Vue

<ais-chat agent-id="YOUR_AGENT_ID" :resume="true" />

boolean | { messages?: boolean; open?: boolean }

default:true

Whether to persist and restore the conversation and the open state of the chat panel from sessionStorage. When true (the default), the widget saves both the messages and whether the panel is open, and restores them when the widget re-mounts. Set it to false to keep everything in memory only.To control each policy separately, pass an object with the messages and open booleans. The widget only persists what you set to true. With a custom chat instance, the instance owns message persistence, so only the open option is available.When the open state isn’t persisted, the prompt gets focus when the chat opens.

Vue

<ais-chat agent-id="YOUR_AGENT_ID" :persistence="{ open: true }" />

boolean

default:false

Whether to skip the validation that requires a way to open the chat. By default, ais-chat logs a development warning unless the chat has an entry point, such as an ais-chat-trigger widget. The inline layout skips this validation automatically. Set this to true when you open the chat programmatically, for example with the setOpen method.

Vue

<ais-chat agent-id="YOUR_AGENT_ID" :disable-trigger-validation="true" />

boolean

default:true

By default, ais-chat requires a main search request. Set requires-search to false to avoid this request when no other widget requires one.

Vue

<ais-chat agent-id="YOUR_AGENT_ID" :requires-search="false" />

(options: { message, messages, isAbort, isDisconnect, isError }) => void

A callback called when the assistant response has finished streaming, including when the stream aborts, disconnects, or fails.The widget also accepts the on-error, on-data, and on-tool-call callbacks, which it forwards to the chat instance it creates.

Vue

<ais-chat
  agent-id="YOUR_AGENT_ID"
  :on-finish="({ message, isAbort, isError }) => trackCompletion(message, isAbort, isError)"
/>

string

The title to display in the chat header.

Vue

<ais-chat agent-id="YOUR_AGENT_ID" title="Shopping assistant" />

'overlay' | 'inline' | 'sidePanel'

default:"'overlay'"

The built-in layout of the chat widget:

overlay. A floating overlay that opens from an entry point, such as ais-chat-trigger.
inline. The chat renders in the page flow and is always visible. It doesn’t require an entry point.
sidePanel. A side panel on the right side of the page. It requires an entry point. By default, it adjusts document.body to make room for the panel. To adjust another element, set parentElement to a CSS selector with layout-props.

For a custom layout, use the layout slot or the layout-component prop. A custom layout component with a $$inlineLayout property set to true skips the trigger validation, like the inline layout.

Vue

<ais-chat
  agent-id="YOUR_AGENT_ID"
  layout="sidePanel"
  :layout-props="{ parentElement: '#main-content' }"
/>

object

Extra props for the built-in layout, such as { parentElement: '#main-content' } for sidePanel.

boolean

default:true

Whether to display the reasoning an agent sends. Set it to false to hide reasoning in this widget, including a custom reasoning slot.This prop can’t make an agent send reasoning. Whether reasoning reaches the browser depends on the agent’s own sendReasoning setting.

Vue

<ais-chat agent-id="YOUR_AGENT_ID" :show-reasoning="false" />

string

default:"messages-end"

Where the loader appears while a chat turn is in progress.

messages-end. Renders the loader in its own row after the last message.
message-inline. Renders the loader inside the streaming assistant message, after the content received so far.

Vue

<ais-chat agent-id="YOUR_AGENT_ID" loader-position="message-inline" />

(context) => boolean

Controls when the loader appears. The function receives the loader context, including status, phase, message, messages, tools, and defaultValue, which indicates whether the widget would show the loader by default.

Vue

<ais-chat
  agent-id="YOUR_AGENT_ID"
  :should-show-loader="({ phase, defaultValue }) => phase === 'tool' || defaultValue"
/>

number

default:250

The delay, in milliseconds, before the loader reappears after it hid earlier in the same turn. The first loader in a turn isn’t delayed.

number

default:200

The shortest time, in milliseconds, that the loader remains visible while the turn is running.

object

Props forwarded to the chat header, merged over the ones the widget sets, such as onClose and maximized.

object

Props forwarded to the messages section of the widget. Use assistantMessageProps and userMessageProps to customize each role separately, for example with textComponent or parseMarkdown. For details, see the React Chat reference.

Vue

<ais-chat
  // ...
  :messages-props="{ userMessageProps: { parseMarkdown: false } }"
/>

object

Props forwarded to the prompt, merged over the ones the widget sets. For example, set autoFocus to control whether the prompt gets focus when the chat opens.

Vue

<ais-chat
  // ...
  :prompt-props="{ autoFocus: false }"
/>

Partial<ChatClassNames>

The CSS classes to add to the widget’s elements. Unlike other Vue InstantSearch widgets, this object uses the same structure as the React Chat widget’s classNames, such as root, container, header, messages, message, and prompt. For the full list, see the React Chat reference.

Vue

<ais-chat
  // ...
  :class-names="{
    root: 'MyCustomChat',
    header: { root: 'MyCustomChatHeader' },
  }"
/>

Partial<ChatTranslations>

A dictionary of translations to customize the UI text, grouped by header, messages, message, and prompt. For the full list, see the React Chat reference.

Vue

<ais-chat
  // ...
  :translations="{
    header: { title: 'My AI shopping assistant' },
    prompt: { textareaPlaceholder: 'Ask me anything' },
  }"
/>

object | (props) => VNode

Each customizable part of the chat UI accepts a Vue component or a render function as a *-component prop. The parts that also have a slot receive the same props as the slot’s scope. A slot takes precedence over the matching prop.

item-component. Each result in the tool carousels and comparison table.
layout-component, header-component, prompt-component, suggestions-component, empty-component, loader-component, actions-component, messages-error-component, reasoning-component, prompt-header-component, prompt-footer-component. The same parts as the matching slots.
header-title-icon-component, header-close-icon-component, header-minimize-icon-component, header-maximize-icon-component. Header icons. The maximize icon receives maximized.
assistant-message-leading-component, assistant-message-footer-component. Assistant message leading element, such as an avatar, and footer.
user-message-leading-component, user-message-footer-component. User message leading element, such as an avatar, and footer.

Vue

<ais-chat
  // ...
  :header-title-icon-component="MyTitleIcon"
/>

Customize the UI

The slot to override the DOM output of each result in the search, recommend, and grouped results carousels, and in the compare products table.Scope

item: object. A single record with all its attributes.
sendEvent: (eventType, hit, eventName) => void. The function to send click or conversion events.

Vue

<ais-chat agent-id="YOUR_AGENT_ID">
  <template v-slot:item="{ item, sendEvent }">
    <a :href="item.url" @click="sendEvent('click', item, 'Product Clicked')">
      {{ item.name }}
    </a>
  </template>
</ais-chat>

The slot to customize the welcome screen shown before the first message.Scope

context.sendMessage. Sends a message to the agent. Call it with { text } to submit a starter prompt.
context.status. The current chat status.
context.onClose. Dismisses the chat.
context.setInput. Sets the value of the prompt input without sending it.

Vue

<ais-chat agent-id="YOUR_AGENT_ID">
  <template v-slot:empty="{ context }">
    <button @click="context.sendMessage({ text: 'Show me new arrivals' })">
      Show me new arrivals
    </button>
  </template>
</ais-chat>

The slot to override the chat header.Scope

onClose: () => void. Closes the chat.
maximized: boolean. Whether the chat takes up the maximized view.
onToggleMaximize: () => void. Toggles the maximized state.
onClear: () => void. Clears the conversation.
canClear: boolean. Whether there’s a conversation to clear.
translations, classNames. The header translations and CSS classes.

Vue

<ais-chat agent-id="YOUR_AGENT_ID">
  <template v-slot:header="{ onClose }">
    <header>
      <span>Shopping assistant</span>
      <button @click="onClose">Close</button>
    </header>
  </template>
</ais-chat>

The slot to customize the loader shown while waiting for an AI response.Scope

translations. The resolved loader translations.
context. The loader context, such as status and phase.
inline. Whether the loader renders inside an assistant message instead of in its own row.

The slot to customize the error message.Scope

errorMessage. The raw error message from the API or transport layer.
onNewConversation. Clears the conversation and starts a new one.
context. The shared chat state.

The slot to render the reasoning of an assistant message, once per reasoning part. :show-reasoning="false" hides it.Scope

part. The reasoning part, with the reasoning text in its text property.
partIndex. The index of the reasoning part in the message’s parts array.
isStreaming. Whether the agent is still streaming this reasoning part.
message. The message the reasoning part belongs to.
context. The shared chat state.

The slot to render follow-up prompt suggestions.Scope

suggestions: string[]. The suggestions.
onSuggestionClick: (suggestion: string) => void. Sends the suggestion as a message.

layout. A custom layout for the whole chat. It receives the same props as the built-in layouts.
prompt. Replaces the prompt.
prompt-header, prompt-footer. Content above and below the prompt input, for example a legal notice.
actions. Replaces the action buttons of assistant messages.

Vue

<ais-chat agent-id="YOUR_AGENT_ID">
  <template v-slot:prompt-footer>
    <a href="https://example.com/privacy-policy">Privacy policy</a>
  </template>
</ais-chat>

Methods

To control the chat from your code, access the widget through a template ref:

setOpen(open: boolean). Opens or closes the chat.
sendMessage(message). Sends a message to the agent, for example { text: "MESSAGE" }, and scrolls the conversation to the bottom.
setInput(input: string). Sets the value of the prompt input without sending it.

Vue

<template>
  <div>
    <button @click="askForDeals">Show me deals</button>
    <ais-chat ref="chat" agent-id="YOUR_AGENT_ID" />
    <ais-chat-trigger />
  </div>
</template>

<script>
  export default {
    methods: {
      askForDeals() {
        this.$refs.chat.setOpen(true);
        this.$refs.chat.sendMessage({ text: "Show me today's deals" });
      },
    },
  };
</script>

​Import

​About this widget

​Examples

​Props

​Customize the UI

​Methods

Import

About this widget

Examples

Props

Customize the UI

Methods