CopilotChat

High-level chat component that connects an agent to a chat view

Overview

CopilotChat is a high-level chat container that wires an agent into CopilotChatView while providing configuration context. It obtains the agent via useAgent, connects to the thread on mount when you pass a threadId, manages pending state, and auto-clears the input after submission. Override any of the internal slots by passing CopilotChatView props directly.

CopilotChat manages messages, running state, and suggestions automatically -- you only need to specify which agent to connect and, optionally, customise labels or slot overrides.

For a walkthrough, see Prebuilt components. To restyle parts of the chat, see Slots.

Import

import { CopilotChat } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";

Props

Own Props

Prop

Type

Inherited CopilotChatView Props

CopilotChat accepts all props from CopilotChatViewProps except messages, isRunning, suggestions, suggestionLoadingIndexes, and onSelectSuggestion, which are managed internally by the agent connection. CopilotChat also manages the view's attachment props (onRemoveAttachment, onAddFile, dragOver, onDragOver, onDragLeave, and onDrop) internally. Its own attachments prop takes an AttachmentsConfig, not the view's Attachment[].

This means you can pass the slot overrides messageView, scrollView, input, suggestionView, welcomeScreen, and intelligenceIndicator directly to CopilotChat. To change the disclaimer, pass input={{ disclaimer: MyDisclaimer }}.

Prop

Type

Slot System

All slot props inherited from CopilotChatView follow the same override pattern. Each slot accepts one of three value types:

ValueBehavior
ComponentReplaces the default component entirely. Receives the same props the default would.
className stringMerged into the default component's class list via twMerge.
Partial props objectSpread into the default component as additional or overriding props.

Additionally, a children render-prop can be used to receive all composed slot elements and arrange them in a custom layout.

Usage

Basic Usage

function App() {
  return (
    <CopilotChat
      agentId="my-agent"
      labels={{ chatInputPlaceholder: "Ask me anything..." }}
    />
  );
}

Custom Welcome Screen

function App() {
  return (
    <CopilotChat
      agentId="my-agent"
      welcomeScreen={({ input, suggestionView }) => (
        <div className="flex flex-col items-center justify-center h-full gap-4">
          <h2>Welcome to the assistant</h2>
          {suggestionView}
          {input}
        </div>
      )}
    />
  );
}

Overriding the Chat View Slot

function App() {
  return (
    <CopilotChat
      agentId="my-agent"
      chatView="bg-gray-50 rounded-xl shadow-lg"
    />
  );
}

Behavior

  • Agent wiring: On mount, CopilotChat calls useAgent with the provided agentId and binds the agent's messages, isRunning, and suggestion state to CopilotChatView.
  • Initial connect: When a threadId is set, CopilotChat calls connectAgent on mount to load the thread's history. The agent runs when the user sends a message.
  • Auto-clear input: After a message is submitted, the input field is cleared automatically.
  • Configuration context: Wraps children in CopilotChatConfigurationProvider, making labels, agentId, threadId, and modal state available to all descendant components via useCopilotChatConfiguration.
  • Suggestion management: Subscribes to the agent's suggestion system and passes suggestions, loading states, and selection callbacks down to CopilotChatView.

How is this guide?