# CopilotChat

> High-level chat 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/components/CopilotChatView) while providing configuration context. It obtains the agent via [`useAgent`](/reference/hooks/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](/prebuilt-components/chat). To restyle parts of the chat, see [Slots](/custom-look-and-feel/slots).

## Import [#import]

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

## Props [#props]

### Own Props [#own-props]

<PropertyReference name="agentId" type="string">
  ID of the agent to use. Must match an agent configured in
  `CopilotKit`. Defaults to the provider-level 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 or let the agent create a new one.
</PropertyReference>

<PropertyReference name="labels" type="Partial<CopilotChatLabels>">
  Partial label overrides for all text strings rendered inside the chat (input
  placeholder, toolbar buttons, disclaimer text, etc.). Any label you omit falls
  back to the built-in default.
</PropertyReference>

<PropertyReference name="chatView" type="SlotValue<React.ComponentType<CopilotChatViewProps>>">
  Slot override for the inner `CopilotChatView` component. Accepts a replacement
  component, a `className` string merged into the default, or a partial props
  object to extend the default.
</PropertyReference>

<PropertyReference name="inspectorTools" type="boolean" default="true">
  Controls Inspector message shortcuts for this chat. An explicit
  `enableInspector` value on the `CopilotKit` provider takes priority: provider
  `true` overrides chat `false`, and provider `false` overrides chat `true`.
  When the provider omits the prop, `inspectorTools={false}` hides this chat's
  shortcuts. Shortcuts only appear on localhost/loopback in development and
  remain hidden while Inspector is temporarily dismissed. This prop does not
  control the shared Inspector launcher.
</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 `onError` (does not suppress it). Only receives errors whose `context.agentId` matches this chat's agent, plus errors without an `agentId` context.

```tsx
<CopilotChat
  agentId="my-agent"
  onError={(event) => {
    if (event.code === "agent_connect_failed") {
      showToast("Could not connect to agent. Please retry.");
    }
  }}
/>
```

</PropertyReference>

<PropertyReference name="isModalDefaultOpen" type="boolean">
  When used inside [`CopilotPopup`](/reference/components/CopilotPopup) or
  [`CopilotSidebar`](/reference/components/CopilotSidebar), controls whether the
  modal starts in the open state. Stored in the chat configuration context so
  child components can read it.
</PropertyReference>

<PropertyReference name="attachments" type="AttachmentsConfig">
  Turns on file attachments (images, audio, video, documents) in the chat
  input. See [Multimodal Attachments](/multimodal-attachments).
</PropertyReference>

<PropertyReference name="throttleMs" type="number">
  Throttle interval in milliseconds for re-renders when messages change.
  Overrides the provider-level `defaultThrottleMs` for this chat. When both are
  unset, re-renders are not throttled. `0` turns off throttling for this chat.
</PropertyReference>

<PropertyReference name="generativeUISurface" type="React.ComponentType<GenerativeUIChatSurfaceProps>">
  Experimental. Wrapper for the generative UI surfaces in this chat. It receives
  `surfaceId`, `isStreaming`, `error`, `rejected`, and `children`.
</PropertyReference>

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

`CopilotChat` accepts all props from [`CopilotChatViewProps`](/reference/components/CopilotChatView) **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 }}`.

<PropertyReference name="autoScroll" type="AutoScrollMode | boolean" default="true">
  Controls how the chat scrolls when messages arrive. `AutoScrollMode` is
  `"pin-to-bottom"`, `"pin-to-send"`, or `"none"`. `true` is `"pin-to-bottom"`,
  and `false` is `"none"`. With `"pin-to-send"`, the chat scrolls only when the
  user sends a message, and pins that message to the top of the view.
</PropertyReference>

<PropertyReference name="input" type="SlotValue<React.ComponentType<CopilotChatInputProps>>">
  Slot for the inner `CopilotChatInput` component. Pass a partial props object
  to configure the default input, for example `input={{ autoFocus: true }}`, or
  pass a replacement component.
</PropertyReference>

<PropertyReference
  name="welcomeScreen"
  type="SlotValue<React.FC<WelcomeScreenProps>> | boolean"
>
  Controls the welcome screen shown when no messages exist. Pass `true` for the
  default, `false` to disable, a `className` to style the default, or a
  replacement component.
</PropertyReference>

<PropertyReference
  name="connectingIndicator"
  type="SlotValue<React.FC<React.HTMLAttributes<HTMLDivElement>>> | boolean"
>
  Loading indicator shown while the chat restores an existing thread's history
  from the agent (only for an explicitly chosen thread, via the `threadId` prop
  or a wrapping `CopilotChatConfigurationProvider`). Pass `false` to disable, a
  `className` to style the default spinner, or a replacement component.
</PropertyReference>

## Slot System [#slot-system]

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

| Value                    | Behavior                                                                            |
| ------------------------ | ----------------------------------------------------------------------------------- |
| **Component**            | Replaces the default component entirely. Receives the same props the default would. |
| **`className` string**   | Merged into the default component's class list via `twMerge`.                       |
| **Partial props object** | Spread 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 [#usage]

### Basic Usage [#basic-usage]

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

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

```tsx
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 [#overriding-the-chat-view-slot]

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

## Behavior [#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`.
