# CopilotChat

> Vue 3 component that connects an agent to a chat view

## Overview [#overview]

`CopilotChat` is a high-level chat container that wires an agent into [`CopilotChatView`](/reference/vue/components/CopilotChatView) while providing configuration context. `CopilotChat` handles these for you:

- Resolves the agent with [`useAgent`](/reference/vue/hooks/useAgent).
- Shows the messages and running state of the agent.
- Manages suggestions.
- Handles the input value and audio transcription.
- Manages file attachments.
- Clears the input after a message is sent.

You typically only need to specify which agent to connect and, optionally, customize labels or override one of the named slots.

<Callout type="info">
  `CopilotChat` also exposes the underlying layout component as `CopilotChat.View`, which is the same component documented at [`CopilotChatView`](/reference/vue/components/CopilotChatView). Use it directly when you want the layout without the agent wiring.
</Callout>

## Import [#import]

```vue
<script setup lang="ts">
import { CopilotChat } from "@copilotkit/vue/v2";
import "@copilotkit/vue/styles.css";
</script>
```

## Props [#props]

All reactive props are declared with `defineProps`. `CopilotChat` extends `CopilotChatView` props but omits the ones it manages internally (`messages`, `isRunning`, `suggestions`, `suggestionLoadingIndexes`, `attachments`, `onRemoveAttachment`, `onAddFile`, `dragOver`, `onDragOver`, `onDragLeave`, `onDrop`).

### Own props [#own-props]

<PropertyReference name="agentId" type="string">
  ID of the agent to connect. Must match an agent configured in `CopilotKitProvider`. Falls back to the `agentId` from a wrapping `CopilotChatConfigurationProvider`, then to the default agent when omitted.
</PropertyReference>

<PropertyReference name="threadId" type="string">
  ID of the conversation thread. Pass a specific thread id to resume an existing conversation. When omitted, a thread id is minted locally and a new thread is created once the agent first runs.
</PropertyReference>

<PropertyReference name="throttleMs" type="number">
  Throttle interval (in milliseconds) forwarded to `useAgent` for batching reactive updates as the agent streams.
</PropertyReference>

<PropertyReference name="labels" type="Partial<CopilotChatLabels>">
  Partial label overrides for the text strings rendered inside the chat (input placeholder, welcome message, toolbar buttons, disclaimer, etc.). Any label you omit falls back to the built-in default. Provided to descendants via [`useCopilotChatConfiguration`](/reference/vue/hooks/useCopilotChatConfiguration).
</PropertyReference>

<PropertyReference name="attachments" type="AttachmentsConfig">
  Configuration for file attachments (accepted MIME types, upload handling, etc.). Set `enabled: true` to turn on the add-file action and drag-and-drop. The chat then manages the attachment queue automatically.
</PropertyReference>

<PropertyReference name="onError" type="(event: { error: Error; code: CopilotKitCoreErrorCode; context: Record<string, any> }) => void | Promise<void>">
  Error handler scoped to this chat's agent. Fires in addition to the provider-level error handling. Only receives errors whose `context.agentId` matches this chat's agent, plus errors without an `agentId` context.

```vue
<script setup lang="ts">
import { CopilotChat } from "@copilotkit/vue/v2";

function handleError(event: {
  error: Error;
  code: string;
  context: Record<string, any>;
}) {
  if (event.code === "agent_connect_failed") {
    showToast("Could not connect to agent. Please retry.");
  }
}
</script>

<template>
  <CopilotChat agent-id="my-agent" :on-error="handleError" />
</template>
```

</PropertyReference>

### Inherited CopilotChatView props [#inherited-copilotchatview-props]

<PropertyReference name="autoScroll" type="AutoScrollMode | boolean" default="true">
  Controls how the chat scrolls as new messages stream in. Accepts `"pin-to-bottom"` / `true` (stick to the bottom while at the bottom), `"pin-to-send"` (anchor the latest user message near the top while the assistant streams), or `"none"` / `false` (never auto-scroll).
</PropertyReference>

<PropertyReference name="welcomeScreen" type="boolean" default="true">
  Whether to show the welcome screen when there are no messages and no explicit thread is selected. Pass `false` to disable it. Override the `welcome-screen` slot to fully customize it.
</PropertyReference>

<PropertyReference name="inputValue" type="string">
  Controlled value for the chat input. When provided, the chat treats the input as controlled and mirrors changes back through the `input-change` event.
</PropertyReference>

<PropertyReference name="inputToolsMenu" type='(ToolsMenuItem | "-")[]'>
  Items for the input's tools menu. Each item has a `label` and either an `action` callback or nested `items`; use `"-"` for a separator.
</PropertyReference>

<PropertyReference name="onFinishTranscribeWithAudio" type="(audioBlob: Blob) => void | Promise<void>">
  Custom handler invoked with the recorded audio blob when transcription finishes. When omitted, `CopilotChat` transcribes the audio using the configured runtime and appends the result to the input.
</PropertyReference>

## Events [#events]

`CopilotChat` emits the following events (listen with `@event-name` in templates). These fire in addition to the component's internal handling, so you can observe interactions without disabling default behavior.

| Event               | Payload                            | Fired when                          |
| ------------------- | ---------------------------------- | ----------------------------------- |
| `submit-message`    | `value: string`                    | A message is submitted              |
| `stop`              | none                               | The stop button is pressed          |
| `input-change`      | `value: string`                    | The input value changes             |
| `select-suggestion` | `suggestion: Suggestion, index: number` | A suggestion pill is selected  |
| `add-file`          | none                               | The add-file action is triggered    |
| `start-transcribe`  | none                               | Audio transcription starts          |
| `cancel-transcribe` | none                               | Audio transcription is cancelled    |
| `finish-transcribe` | none                               | Audio transcription finishes        |

## Slots [#slots]

Vue uses named slots in place of React's render props and sub-component props. Provide a slot to replace the corresponding piece of the chat. Each slot receives scoped props you can destructure with `v-slot`. Any slot not listed below is forwarded down through `CopilotChatView` to the message view.

<PropertyReference name="chat-view" type="CopilotChatViewOverrideSlotProps">
  Replaces the entire inner `CopilotChatView`. Receives all of the composed view state and handlers (`messages`, `isRunning`, `suggestions`, `inputValue`, `onSubmitMessage`, `onSelectSuggestion`, `onStop`, transcription and attachment handlers, etc.) so you can render a fully custom layout.
</PropertyReference>

<PropertyReference name="message-view" type="{ messages: Message[]; isRunning: boolean }">
  Replaces the default message list rendering.
</PropertyReference>

<PropertyReference name="input" type="CopilotChatInputSlotProps">
  Replaces the default chat input. Receives `modelValue`, `isRunning`, `inputMode`, `inputToolsMenu`, and handlers such as `onUpdateModelValue`, `onSubmitMessage`, `onStop`, and the transcription callbacks.
</PropertyReference>

<PropertyReference name="suggestion-view" type="CopilotChatSuggestionViewSlotProps">
  Replaces the default suggestion pills. Receives `suggestions`, `loadingIndexes`, and `onSelectSuggestion`. Suggestions come from [`useSuggestions`](/reference/vue/hooks/useSuggestions).
</PropertyReference>

<PropertyReference name="welcome-screen" type="CopilotChatWelcomeScreenSlotProps">
  Replaces the default welcome screen shown when no messages exist. Receives the suggestion props plus the input model value and submission handlers, letting you compose your own greeting layout.
</PropertyReference>

<PropertyReference name="welcome-message" type="() => unknown">
  Replaces only the heading text inside the default welcome screen, leaving the surrounding layout intact.
</PropertyReference>

<PropertyReference name="interrupt" type="CopilotChatInterruptSlotProps">
  Renders human-in-the-loop interrupt UI. Receives the `event`, current `result`, and a `resolve` callback.
</PropertyReference>

<PropertyReference name="generative-ui-surface" type="GenerativeUIChatSurfaceSlotProps">
  Experimental. Replaces the default card around each [generative UI](/reference/vue/components/GenerativeUISurface) surface that the agent renders in this chat. It applies only when the provider has a [`generativeUI`](/reference/vue/components/CopilotKitProvider) config. Slot props:

- `surfaceId` (`string`): the id of the surface.
- `isStreaming` (`boolean`): `true` while the agent streams operations into the surface.
- `error` (`Error | undefined`): set when operations from the latest `render_ui` call were rejected. The message is safe to show to the user.
- `rejected` (`GenerativeUIRejectedOperation[]`): the rejected operations, with the reason for each.
- `children` (`VNode | null`): the rendered surface. Render it with `<component :is="children" />`. It is `null` when the creation of the surface failed. Then the card shows only the error.

</PropertyReference>

<Callout type="info">
  Slots forwarded to the message view (for example custom assistant- or user-message slots) are passed straight through and rendered by `CopilotChatMessageView`. See [`CopilotChatView`](/reference/vue/components/CopilotChatView) for the full set of layout-level slots such as `scroll-view`, `feather`, and `scroll-to-bottom-button`.
</Callout>

## Usage [#usage]

### Basic usage [#basic-usage]

```vue
<script setup lang="ts">
import { CopilotChat } from "@copilotkit/vue/v2";
import "@copilotkit/vue/styles.css";
</script>

<template>
  <CopilotChat
    agent-id="my-agent"
    :labels="{ chatInputPlaceholder: 'Ask me anything...' }"
  />
</template>
```

### Custom welcome screen [#custom-welcome-screen]

```vue
<script setup lang="ts">
import { CopilotChat } from "@copilotkit/vue/v2";
</script>

<template>
  <CopilotChat agent-id="my-agent">
    <template #welcome-screen="{ onSubmitMessage, suggestions, onSelectSuggestion }">
      <div class="flex h-full flex-col items-center justify-center gap-4">
        <h2>Welcome to the assistant</h2>
        <button
          v-for="(suggestion, index) in suggestions"
          :key="index"
          @click="onSelectSuggestion(suggestion, index)"
        >
          {{ suggestion.title }}
        </button>
      </div>
    </template>
  </CopilotChat>
</template>
```

### Custom generative UI card [#custom-generative-ui-card]

```vue
<script setup lang="ts">
import { CopilotChat } from "@copilotkit/vue/v2";
</script>

<template>
  <CopilotChat agent-id="my-agent">
    <template #generative-ui-surface="{ isStreaming, error, children }">
      <section class="my-card" :aria-busy="isStreaming">
        <p v-if="error" role="alert">{{ error.message }}</p>
        <component :is="children" v-if="children" />
      </section>
    </template>
  </CopilotChat>
</template>
```

### Observing events [#observing-events]

```vue
<script setup lang="ts">
import { CopilotChat } from "@copilotkit/vue/v2";

function onSubmit(value: string) {
  console.log("user submitted:", value);
}
</script>

<template>
  <CopilotChat agent-id="my-agent" @submit-message="onSubmit" />
</template>
```

### Using the layout directly [#using-the-layout-directly]

`CopilotChat.View` is the layout component without agent wiring. Use it when you manage `messages` and handlers yourself.

```vue
<script setup lang="ts">
import { CopilotChat } from "@copilotkit/vue/v2";
import { ref } from "vue";

// Vue SFC templates cannot resolve dotted tags like `<CopilotChat.View>`,
// so alias the layout to a local component first.
const ChatView = CopilotChat.View;

const messages = ref([]);

function handleSubmit(value: string) {
  // manage your own message state
}
</script>

<template>
  <ChatView :messages="messages" @submit-message="handleSubmit" />
</template>
```
