# CopilotChatView

> Layout component that combines a scrollable transcript with the input area

## Overview [#overview]

`CopilotChatView` is a layout component that combines a scrollable transcript with the chat input area, suggestion pills, a scroll-to-bottom button, and an optional welcome screen. It is the visual core of the chat interface and is used internally by [`CopilotChat`](/reference/components/CopilotChat), [`CopilotPopup`](/reference/components/CopilotPopup), and [`CopilotSidebar`](/reference/components/CopilotSidebar).

Every visual piece of `CopilotChatView` is exposed as a **slot**, so you can replace, style, or extend any part without rewriting the entire layout.

## Import [#import]

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

<Callout type="info">
  `CopilotChatView` is a **named** export of the `@copilotkit/react-core/v2`
  entry point. The package root, `@copilotkit/react-core`, does not export it.
</Callout>

## Slots [#slots]

`CopilotChatView` uses the `WithSlots` pattern. Each slot prop 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.                |

Pass a `children` function to get the `messageView`, `input`, `scrollView`, and `suggestionView` elements, and arrange them in your own layout. The `scrollView` element already contains the message view and the suggestions.

### Slot Props [#slot-props]

<PropertyReference
  name="messageView"
  type="SlotValue<typeof CopilotChatMessageView>"
>
  The component that renders the transcript. The
  default displays assistant messages, user messages, and a typing cursor.
  Replace it to add custom message types or modify the message layout.
</PropertyReference>

<PropertyReference
  name="scrollView"
  type="SlotValue<typeof CopilotChatView.ScrollView>"
>
  The scrollable container that wraps the transcript. The default handles
  auto-scroll behavior and scroll position tracking. Replace it to implement
  custom scroll mechanics.
</PropertyReference>

<PropertyReference
  name="scrollView.scrollToBottomButton"
  type="SlotValue<React.FC<ButtonProps>>"
>
  A button that appears when the user has scrolled up from the bottom of the
  transcript. Clicking it scrolls the view back to the latest message. Pass it
  through the `scrollView` slot: `scrollView={{ scrollToBottomButton: MyButton }}`.
  Here `ButtonProps` is `React.ButtonHTMLAttributes<HTMLButtonElement>`.
</PropertyReference>

<PropertyReference
  name="scrollView.feather"
  type="SlotValue<React.FC<React.HTMLAttributes<HTMLDivElement>>>"
>
  An empty element that the scroll view renders below the scrolling messages.
  It has no style by default. Pass a className or a component through the
  `scrollView` slot: `scrollView={{ feather: "my-class" }}`.
</PropertyReference>

<PropertyReference name="input" type="SlotValue<typeof CopilotChatInput>">
  The message input component. The default provides a text area with send
  button, transcription controls, file upload, and a tools menu. Replace it to
  build a fully custom input experience. To pass more props to the default
  input, use a props object, for example `input={{ autoFocus: true }}`.
</PropertyReference>

<PropertyReference
  name="disclaimer"
  type="SlotValue<React.FC<React.HTMLAttributes<HTMLDivElement>>>"
>
  **Deprecated.** Use the `disclaimer` slot of the `input` slot:
  `input={{ disclaimer: MyDisclaimer }}`. A disclaimer text line displayed below
  the input (for example "AI can make mistakes. Please verify important
  information."). Override or hide it with a replacement component.
</PropertyReference>

<PropertyReference
  name="suggestionView"
  type="SlotValue<typeof CopilotChatSuggestionView>"
>
  The component that renders suggestion pills. Replace it to change how
  suggestions are displayed or animated.
</PropertyReference>

## Data Props [#data-props]

<PropertyReference name="messages" type="Message[]">
  Array of conversation messages to display. Inside `CopilotChat`, the chat
  passes the agent messages to the view. When you use `CopilotChatView` on its
  own, pass the messages yourself.
</PropertyReference>

<PropertyReference name="autoScroll" type='"pin-to-bottom" | "pin-to-send" | "none" | boolean' default="true">
  How the view scrolls when messages arrive:

- `"pin-to-bottom"` or `true`: keep the latest message in view while the user is at the bottom.
- `"pin-to-send"`: when the user sends a message, scroll that message to the top of the view and keep it there while the reply streams.
- `"none"` or `false`: do not scroll automatically.

</PropertyReference>

<PropertyReference name="isRunning" type="boolean">
  Whether the agent is currently processing. When `true`, the input shows a stop
  button and the message view displays a typing cursor on the latest assistant
  message.
</PropertyReference>

<PropertyReference name="suggestions" type="Suggestion[]">
  Array of suggestion objects to display as clickable pills below (or above) the
  input area. Each suggestion has a `title`, a `message`, an `isLoading` flag,
  and an optional `className`.
</PropertyReference>

<PropertyReference name="suggestionLoadingIndexes" type="ReadonlyArray<number>">
  Indexes of suggestions that are currently in a loading state (e.g. the user
  just clicked them and the agent is processing).
</PropertyReference>

<PropertyReference
  name="onSelectSuggestion"
  type="(suggestion: Suggestion, index: number) => void"
>
  Callback invoked when the user clicks a suggestion pill. Receives the selected
  suggestion object and its index.
</PropertyReference>

<PropertyReference name="welcomeScreen" type='SlotValue<React.FC<WelcomeScreenProps>> | boolean'>
  Controls the welcome screen shown when the `messages` array is empty.

- `true` -- show the default welcome screen
- `false` -- disable the welcome screen
- **`className` string** -- style the default welcome screen
- **Component** -- replace the welcome screen entirely

The welcome screen component receives `input` and `suggestionView` as React elements, plus a `welcomeMessage` slot, so you can compose them in any layout.

</PropertyReference>

<PropertyReference name="connectingIndicator" type='SlotValue<React.FC<React.HTMLAttributes<HTMLDivElement>>> | boolean'>
  Controls the loading indicator shown while a thread's history is being restored (`isConnecting` is `true` and `messages` is still empty).

- `true` (default) -- show the default spinner
- `false` -- disable the indicator
- **`className` string** -- style the default indicator
- **Component** -- replace the indicator entirely

</PropertyReference>

## Static Sub-Components [#static-sub-components]

`CopilotChatView` exposes its default slot implementations as static properties for use in custom compositions:

- `CopilotChatView.ScrollView` -- default scroll container with auto-scroll support
- `CopilotChatView.ScrollToBottomButton` -- default scroll-to-bottom button
- `CopilotChatView.Feather` -- default feather, an empty element
- `CopilotChatView.ConnectingIndicator` -- default loading indicator shown while a thread connects
- `CopilotChatView.WelcomeMessage` -- default welcome message
- `CopilotChatView.WelcomeScreen` -- default welcome screen layout

## Usage [#usage]

### Standalone Usage [#standalone-usage]

```tsx
function CustomChat({ messages, isRunning }) {
  return (
    <CopilotChatView
      messages={messages}
      isRunning={isRunning}
      autoScroll={true}
    />
  );
}
```

### Replacing a Slot with a Custom Component [#replacing-a-slot-with-a-custom-component]

```tsx
function CustomDisclaimer(props) {
  return (
    <div {...props}>Powered by CopilotKit. Responses may contain errors.</div>
  );
}

function Chat({ messages, isRunning }) {
  return (
    <CopilotChatView
      messages={messages}
      isRunning={isRunning}
      input={{ disclaimer: CustomDisclaimer }}
    />
  );
}
```

### Styling a Slot with a className [#styling-a-slot-with-a-classname]

```tsx
function Chat({ messages, isRunning }) {
  return (
    <CopilotChatView
      messages={messages}
      isRunning={isRunning}
      scrollView="bg-gray-50"
      input="border-t border-gray-200"
    />
  );
}
```

### Custom Layout with Children Render-Prop [#custom-layout-with-children-render-prop]

```tsx
function Chat({ messages, isRunning }) {
  return (
    <CopilotChatView messages={messages} isRunning={isRunning}>
      {({ scrollView, input }) => (
        <div className="flex flex-col h-full">
          <div className="flex-1 overflow-hidden">{scrollView}</div>
          {input}
        </div>
      )}
    </CopilotChatView>
  );
}
```

## Behavior [#behavior]

- **Auto-scroll**: When `autoScroll` is `true`, the view uses a stick-to-bottom strategy that keeps the latest message visible. A scroll-to-bottom button appears when the user scrolls up.
- **Welcome screen**: When `messages` is empty and `welcomeScreen` is not `false`, a welcome screen is rendered in place of the transcript. The welcome screen also stays hidden while the thread connects (`isConnecting`) and when the chat targets a specific thread (`hasExplicitThreadId`). The welcome screen receives the `input` and `suggestionView` elements so they can be placed within the welcome layout.
- **Connecting state**: While a thread's initial connect is in flight and no messages have arrived, the `connectingIndicator` is rendered in the transcript area. The root element exposes `data-copilot-connecting="true"` for the duration of the connect, so apps can style their own loading state with CSS.
- **Input container positioning**: The input container is absolutely positioned at the bottom of the chat, and the scroll area pads its content to avoid overlap.
- **Resize handling**: The scroll view monitors input container height changes to keep padding in sync and hides the scroll-to-bottom button during resize transitions.
