examples/v2/docs/reference/copilot-chat.mdx
CopilotChat is a React component that provides a complete chat interface for interacting with AI agents. It handles
message display, user input, tool execution rendering, and agent communication automatically.
The CopilotChat component:
CopilotChat is built on a composable component hierarchy. Understanding this structure helps you customize exactly what you need.
graph LR
CC[CopilotChat] --> messageView
CC --> scrollView
CC --> input
CC --> suggestionView
CC --> welcomeScreen
| Slot | Description | Reference |
|---|---|---|
messageView | Container for the message list (user and assistant messages) | CopilotChatMessageView |
scrollView | Scrollable container with auto-scroll behavior | CopilotChatScrollView |
input | Text input with toolbar, transcription support, and disclaimer | CopilotChatInput |
suggestionView | Clickable suggestion chips | CopilotChatSuggestionView |
welcomeScreen | Initial screen before any messages | CopilotChatWelcomeScreen |
See Slot Customization for details on how to customize these slots.
import { CopilotChat, CopilotKitProvider } from "@copilotkit/react-core";
function App() {
return (
<CopilotKitProvider runtimeUrl="/api/copilotkit">
<CopilotChat />
</CopilotKitProvider>
);
}
string (optional)
The ID of the agent to connect to. Defaults to "default".
<CopilotChat agentId="assistant" />
string (optional)
The conversation thread ID. If not provided, a new thread ID is automatically generated.
When you provide a threadId, CopilotChat automatically loads the conversation history for that thread, including any messages that are currently streaming. This enables seamless continuation of conversations across page reloads or component remounts.
<CopilotChat threadId="thread-123" />
Partial<CopilotChatLabels> (optional)
Customize the text labels used throughout the chat interface.
<CopilotChat
labels={{
chatInputPlaceholder: "Ask me anything...",
chatDisclaimerText: "AI assistant - verify important info",
welcomeMessage: "Hello! How can I help you today?",
}}
/>
boolean (optional, default: true)
Automatically scroll to the bottom when new messages appear.
<CopilotChat autoScroll={false} />
string (optional)
CSS class name for the root container.
<CopilotChat className="h-screen bg-white" />
boolean (optional)
When using CopilotChat in modal mode, controls whether the modal is open by default.
<CopilotChat isModalDefaultOpen={true} />
SlotValue<typeof CopilotChatView> (optional)
Customize the main chat view component. See Slot Customization for details.
CopilotChat uses a powerful slot system that allows you to customize any part of the UI. Each slot accepts four types of values:
The simplest way to customize appearance is with Tailwind class strings:
<CopilotChat
className="bg-gradient-to-b from-white to-gray-50 rounded-xl shadow-2xl"
messageView="space-y-4"
input="border-2 border-gray-200"
/>
Pass a props object to modify component behavior while keeping the default implementation:
<CopilotChat
messageView={{ className: "custom-message-view" }}
input={{ placeholder: "Ask a question..." }}
scrollView="custom-scroll-view"
/>
You can drill down into nested components through props objects:
<CopilotChat
messageView={{
assistantMessage: {
onThumbsUp: () => console.log("thumbsUp"),
onThumbsDown: () => console.log("thumbsDown"),
},
}}
/>
For full control, replace components entirely:
import { CopilotChatView } from "@copilotkit/react-core";
function CustomChatView(props) {
return (
<div className="custom-chat-layout">
<CopilotChatView
{...props}
messageView="custom-message-from-wrapper"
input="custom-input-from-wrapper"
/>
</div>
);
}
<CopilotChat chatView={CustomChatView} />;
The messageView slot controls how messages are rendered:
<CopilotChat
messageView={{
// Style the message container
className: "space-y-4 p-4",
// Customize assistant messages
assistantMessage: {
className: "bg-blue-50 rounded-lg",
onThumbsUp: (message) => trackFeedback(message.id, "positive"),
onThumbsDown: (message) => trackFeedback(message.id, "negative"),
},
// Customize user messages
userMessage: "bg-gray-100 rounded-lg",
// Customize the typing cursor
cursor: "bg-blue-500",
}}
/>
Customize how assistant messages appear and behave:
<CopilotChat
messageView={{
assistantMessage: {
className: "bg-slate-50 border border-slate-200 rounded-xl p-4",
onThumbsUp: (message) => sendFeedback(message.id, "positive"),
onThumbsDown: (message) => sendFeedback(message.id, "negative"),
onRegenerate: (message) => regenerateResponse(message.id),
},
}}
/>
For full details on assistant message slots and customization options, see CopilotChatAssistantMessage.
Customize how user messages appear:
<CopilotChat
messageView={{
userMessage: "bg-blue-500 text-white rounded-2xl px-4 py-2",
}}
/>
You can also pass a props object or a custom component:
<CopilotChat
messageView={{
userMessage: {
className: "bg-primary text-primary-foreground",
"data-testid": "user-message",
},
}}
/>
The input slot controls the text input and its toolbar:
<CopilotChat
input={{
className: "border-2 border-primary rounded-xl",
placeholder: "Type your message...",
// Customize individual buttons
sendButton: "bg-blue-500 hover:bg-blue-600",
}}
/>
For full details on input slots and customization options, see CopilotChatInput.
CopilotChat automatically manages suggestion chips through the useSuggestions hook. Suggestions are generated by the agent and displayed as clickable chips that users can select to quickly send messages.
You can customize suggestions through the suggestionView slot, which has two sub-slots:
<CopilotChat
suggestionView={{
// Customize the container that holds all chips
container: "gap-4",
// Customize individual suggestion chips
suggestion: "bg-blue-100 hover:bg-blue-200 rounded-full",
}}
/>
CopilotChat supports voice input through transcription. To enable it, configure your CopilotKitProvider with transcription settings:
<CopilotKitProvider
runtimeUrl="/api/copilotkit"
transcribeAudioUrl="/api/transcribe"
>
<CopilotChat />
</CopilotKitProvider>
Once enabled, a microphone button appears in the input toolbar. Users can record audio which is transcribed and inserted into the message input.
The welcome screen is displayed before any messages are sent. You can customize it in several ways:
The simplest customization is changing the welcome message text:
<CopilotChat
labels={{
welcomeMessage: "Hello! I'm your AI assistant. How can I help you today?",
}}
/>
For full control, replace the entire welcome screen:
function CustomWelcomeScreen() {
return (
<div className="flex flex-col items-center justify-center h-full p-8">
<h2 className="text-2xl font-bold mb-2">Welcome to AI Assistant</h2>
<p className="text-muted-foreground text-center">
Ask me anything about your data, documents, or tasks.
</p>
</div>
);
}
<CopilotChat welcomeScreen={CustomWelcomeScreen} />;
CopilotChat automatically scrolls to the bottom when:
autoScroll prop is true (default)The scroll-to-bottom button appears when the user scrolls up and new content is available.
// Disable auto-scroll
<CopilotChat autoScroll={false} />
// Customize the scroll button
<CopilotChat scrollView={{ scrollToBottomButton: "bg-blue-500 rounded-full shadow-lg" }} />
Here's a fully customized CopilotChat implementation:
import { CopilotChat, CopilotKitProvider } from "@copilotkit/react-core";
function App() {
const handleFeedback = (messageId: string, type: "positive" | "negative") => {
analytics.track("message_feedback", { messageId, type });
};
return (
<CopilotKitProvider runtimeUrl="/api/copilotkit">
<div className="h-screen">
<CopilotChat
agentId="my-assistant"
className="h-full"
labels={{
chatInputPlaceholder: "Ask me anything...",
chatDisclaimerText: "AI responses may not be accurate.",
welcomeMessage: "Hello! I'm here to help.",
}}
messageView={{
assistantMessage: {
onThumbsUp: (msg) => handleFeedback(msg.id, "positive"),
onThumbsDown: (msg) => handleFeedback(msg.id, "negative"),
},
}}
input={{
className: "border-2 border-gray-200 rounded-xl",
disclaimer: "text-xs text-gray-400",
}}
/>
</div>
</CopilotKitProvider>
);
}