showcase/shell-docs/src/content/reference/vue/components/CopilotChat.mdx
CopilotChat is a high-level chat container that wires an agent into CopilotChatView while providing configuration context. It resolves the agent via useAgent, subscribes to the agent's messages and running state, manages suggestions, handles input value and audio transcription, wires file attachments, and auto-clears the input after a message is submitted.
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><script setup lang="ts">
import { CopilotChat } from "@copilotkit/vue/v2";
import "@copilotkit/vue/styles.css";
</script>
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).
<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>
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 |
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.
<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>
<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>
<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>
CopilotChat.View is the layout component without agent wiring. Use it when you manage messages and handlers yourself.
<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>
CopilotChatView - the layout component used internally (also exposed as CopilotChat.View)useAgent - composable used internally to resolve the agentuseSuggestions - composable that powers the suggestion pillsuseCopilotChatConfiguration - reads the labels, agent id, and thread id provided by CopilotChat