# CopilotChatMessageView

> Component for rendering a list of chat messages

## Overview [#overview]

`CopilotChatMessageView` renders a list of chat messages and, optionally, a typing cursor while the agent is running. It delegates rendering of individual messages to slot components (`assistantMessage` and `userMessage`) and supports a render-prop `children` function for full control over layout. [`CopilotChatView`](/reference/components/CopilotChatView) renders it as its `messageView` slot.

## Import [#import]

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

## Props [#props]

<PropertyReference name="isRunning" type="boolean" default="false">
  Whether the agent is currently executing. When `true`, the cursor slot is
  rendered after the last message to indicate ongoing activity.
</PropertyReference>

<PropertyReference name="messages" type="Message[]" default="[]">
  The array of chat messages to render. Messages with role `"user"`,
  `"assistant"`, `"reasoning"`, or `"activity"` render.
</PropertyReference>

<PropertyReference name="transformMessages" type="(messages: Message[]) => Message[]">
  Reshapes the list before it renders: drop, replace or reorder messages with
  the whole list in view. Receives the messages after duplicate ids are merged
  and returns the list to render. Virtualization, row keys, scroll-to-bottom
  and the "latest message" all follow the returned list, so a dropped message
  takes no row. Tool-call cards still look up their results in the full
  `messages`, so hiding tool-result messages does not empty them.

  Rules:

  - Return each id at most once.
  - Give any message you build an id that stays the same while the thread
    streams.
  - Pass a stable function (for example with `useCallback`). The transform
    reruns when `messages` or the function change.

  See [Reshaping the Message List](/custom-look-and-feel/slots#reshaping-the-message-list).
</PropertyReference>

<PropertyReference name="groupMessages" type="(messages: Message[]) => MessageRow[]">
  Splits the list into rows. Return `messageRow(message)` for a message that
  renders on its own and `messageGroup({ key, messages, wrapper })` for messages
  that render together inside `wrapper`, which receives `groupKey`, `messages`,
  `children` (the default rendering of those messages), and `state` /
  `setState`. Each row is one virtualized row. Receives the list after
  `transformMessages`.

  The chat keeps the state of a group under its `key`, so the state survives
  the row leaving the window. The chat drops the state when the key stops
  appearing, and clears it when the thread changes.

  Rules:

  - Place each message in at most one row.
  - Keep keys stable while the thread streams.
  - Define wrappers at module level.
  - Pass a stable function.

  See [Grouping messages into one row](/custom-look-and-feel/slots#grouping-messages-into-one-row).
</PropertyReference>

<PropertyReference name="messageFeedback" type="boolean" default="true">
  Whether reply thumbs record ratings for Automatic Learning once a Trajectory
  has started. Set `false` to keep the thumbs to your own `onThumbsUp` /
  `onThumbsDown` handlers and slots. See
  [Collect reply ratings](/intelligence/capture-interactions#collect-reply-ratings).
</PropertyReference>

<PropertyReference name="toolCallDisplay" type='"grouped" | "line" | "stacked" | "turn" | "separate"' default='"grouped"'>
  How tool calls show in the list.

- `"grouped"` (default): calls the agent makes in a row share one card,
  collapsed to a summary ("Used 3 tools · run_command ×2, read_file"). While a
  call runs, the summary names it. Opening the card shows a row per call, and
  each row opens to its arguments and result.
- `"line"`: the same grouping as a quiet line of text, like the reasoning
  message's "Thought for 4 seconds". It opens to a list of rows.
- `"stacked"`: the latest call on top of a stack of the earlier ones. Clicking
  the stack fans it out into a card per call.
- `"turn"`: the agent works in the open. A "Working" line sits at the top of
  the reply, narration fades to muted once a call follows it, and calls appear
  as rows. When the reply is done, everything before it folds into "Worked for
  9s", leaving only the reply. The line is the
  [`workSummary`](#worksummary) slot.
- `"separate"`: every call gets its own card.

Grouping applies to calls drawn by a renderer that opts into it, which the
built-in card from [`useDefaultRenderTool()`](/reference/hooks/useDefaultRenderTool)
does. A custom catch-all opts in with `group: true`; until then its calls show
on their own, since the chat can't tell what it draws (it may draw nothing).
Any call that isn't grouped splits the group around it, and so do text,
reasoning and activity messages. Calls with no renderer at all still render
nothing. To restyle or replace the group itself, use the `group` slot of
[`CopilotChatToolCallsView`](/reference/components/CopilotChatAssistantMessage#copilotchattoolcallsview).
See [Grouping tool calls](/generative-ui/tool-rendering#grouping-tool-calls).
</PropertyReference>

<PropertyReference name="children" type="(props: { isRunning: boolean; messages: Message[]; messageElements: React.ReactElement[]; interruptElement: React.ReactElement | null }) => React.ReactElement">
Optional render-prop function that receives the resolved state and pre-built message elements. When provided, the component calls this function instead of rendering the default message list layout. The callback receives `isRunning` (current running state), `messages` (the raw message array), `messageElements` (an array of React elements built from the `assistantMessage` and `userMessage` slots), and `interruptElement` (the interrupt UI from `useInterrupt`, or `null`). The default layout renders `interruptElement` after the messages, so place it in your layout too. Providing `children` turns virtualization off, so every message is mounted; for list-level changes, prefer `transformMessages`.
</PropertyReference>

## Slots [#slots]

All slot props follow the CopilotKit slot system: each accepts a replacement React component, a `className` string that is merged into the default component's classes, or a partial props object that extends the default component.

<PropertyReference name="assistantMessage" type="SlotValue<typeof CopilotChatAssistantMessage>">
  Slot for rendering assistant messages. Defaults to [`CopilotChatAssistantMessage`](/reference/components/CopilotChatAssistantMessage), which provides Markdown rendering, tool call display, and an action toolbar.

**As a replacement component:**

```tsx
<CopilotChatMessageView
  assistantMessage={({ message }) => (
    <div className="my-assistant-msg">{message.content}</div>
  )}
/>
```

**As a className:**

```tsx
<CopilotChatMessageView assistantMessage="bg-blue-50 rounded-lg" />
```

**As partial props:**

```tsx
<CopilotChatMessageView assistantMessage={{ toolbarVisible: false }} />
```

</PropertyReference>

<PropertyReference name="userMessage" type="SlotValue<typeof CopilotChatUserMessage>">
  Slot for rendering user messages. Defaults to [`CopilotChatUserMessage`](/reference/components/CopilotChatUserMessage), which provides right-aligned message display with optional branch navigation.

**As a replacement component:**

```tsx
<CopilotChatMessageView
  userMessage={({ message }) => (
    <div className="my-user-msg">{message.content}</div>
  )}
/>
```

**As a className:**

```tsx
<CopilotChatMessageView userMessage="bg-gray-100 rounded-lg" />
```

</PropertyReference>

<PropertyReference name="reasoningMessage" type="SlotValue<typeof CopilotChatReasoningMessage>">
  Slot for rendering reasoning messages. Defaults to `CopilotChatReasoningMessage`,
  a collapsible block that reads "Thought for" with the elapsed time once the
  reasoning ends.
</PropertyReference>

<PropertyReference name="cursor" type="SlotValue<typeof CopilotChatMessageView.Cursor>">
  Slot for the typing indicator displayed while `isRunning` is `true`. Defaults to `CopilotChatMessageView.Cursor`, which renders a pulsing dot animation.

**As a replacement component:**

```tsx
<CopilotChatMessageView
  cursor={() => <span className="animate-bounce">...</span>}
/>
```

**As a className:**

```tsx
<CopilotChatMessageView cursor="text-blue-500" />
```

</PropertyReference>

<PropertyReference name="workSummary" type="SlotValue<typeof CopilotChatWorkSummary>">
  Slot for the line at the top of each reply in the `"turn"` tool-call
  display. Defaults to
  [`CopilotChatWorkSummary`](/reference/components/CopilotChatToolCallGroup#copilotchatworksummary).
  It reads "Working" with a timer while the agent works, then "Worked for 9s"
  once the reply is done, and toggles the work it folded away. Only rendered
  when `toolCallDisplay` is `"turn"`.

**As a className:**

```tsx
<CopilotChatMessageView toolCallDisplay="turn" workSummary="text-xs" />
```

**As a replacement component:**

```tsx
<CopilotChatMessageView
  toolCallDisplay="turn"
  workSummary={({ isWorking, isOpen, calls, onClick }) => (
    <button onClick={onClick} aria-expanded={isOpen}>
      {isWorking ? "Thinking it through…" : `Checked ${calls.length} sources`}
    </button>
  )}
/>
```

</PropertyReference>

## Usage [#usage]

### Basic Message List [#basic-message-list]

```tsx
function MessageList() {
  const { agent } = useAgent();

  return (
    <CopilotChatMessageView
      messages={agent.messages}
      isRunning={agent.isRunning}
    />
  );
}
```

### Customizing Message Slots [#customizing-message-slots]

```tsx
function CustomMessages() {
  const { agent } = useAgent();

  return (
    <CopilotChatMessageView
      messages={agent.messages}
      isRunning={agent.isRunning}
      assistantMessage="bg-blue-50 p-4 rounded-xl"
      userMessage="bg-gray-100 p-4 rounded-xl"
      cursor={() => (
        <div className="animate-pulse text-gray-400">Thinking...</div>
      )}
    />
  );
}
```

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

```tsx
function CustomLayout() {
  const { agent } = useAgent();

  return (
    <CopilotChatMessageView
      messages={agent.messages}
      isRunning={agent.isRunning}
    >
      {({ isRunning, messages, messageElements, interruptElement }) => (
        <div className="flex flex-col gap-4 p-6">
          <div className="text-sm text-gray-500">
            {messages.length} message{messages.length !== 1 ? "s" : ""}
          </div>
          {messageElements}
          {interruptElement}
          {isRunning && (
            <div className="text-sm text-blue-500 animate-pulse">
              Agent is responding...
            </div>
          )}
        </div>
      )}
    </CopilotChatMessageView>
  );
}
```

### Choosing How Tool Calls Show [#choosing-how-tool-calls-show]

```tsx
function AgentChat() {
  const { agent } = useAgent();

  return (
    <CopilotChatMessageView
      messages={agent.messages}
      isRunning={agent.isRunning}
      toolCallDisplay="turn"
    />
  );
}
```

From `CopilotChat`, `CopilotSidebar` or `CopilotPopup`, set it through the
`messageView` slot:

```tsx
<CopilotChat messageView={{ toolCallDisplay: "line" }} />
```

To give every call its own card:

```tsx
<CopilotChat messageView={{ toolCallDisplay: "separate" }} />
```

### Hiding the Toolbar on Assistant Messages [#hiding-the-toolbar-on-assistant-messages]

```tsx
function MinimalChat() {
  const { agent } = useAgent();

  return (
    <CopilotChatMessageView
      messages={agent.messages}
      isRunning={agent.isRunning}
      assistantMessage={{ toolbarVisible: false }}
    />
  );
}
```

## Behavior [#behavior]

- **Message Rendering**: Each message in the `messages` array is rendered using the corresponding slot component based on its `role`. Assistant messages use the `assistantMessage` slot; user messages use the `userMessage` slot. Reasoning messages use the `reasoningMessage` slot.
- **Cursor Display**: The `cursor` slot is only rendered when `isRunning` is `true`. It appears after the last message in the list, and is hidden when the last rendered message is a reasoning message, which shows its own indicator.
- **Virtualization**: Inside a chat scroll container, once more than 50 messages render, only the rows on screen are mounted. The count is of the messages that render: the ones `transformMessages` returns or, with `groupMessages`, the ones in the rows it returns. The window itself moves by rows, and each group is one row. Providing `children` turns virtualization off; in development the component warns once when that is what keeps a long thread mounted in full.
- **Latest Message**: The last rendered message is passed to its slot as `isLatest`. While `isRunning` is `true`, the latest assistant message hides its toolbar and a latest reasoning message shows as streaming.
- **Tool-Call Groups**: Groups can span messages, since agents often send each call as its own assistant message. The group belongs to the message where it starts, and the later messages whose calls joined it render no tool calls of their own. While the agent is running and nothing follows a group, its summary names the call in progress.
- **Work Summary**: In the `"turn"` display:
  - The summary replaces the cursor while the reply is in progress.
  - "Worked for 9s" adds up the runs of the agent on the reply. Time spent waiting between runs (for an approval, for example) does not count.
  - The timer needs a reply that this component saw start. A restored thread shows the tool count ("Used 7 tools") instead.
  - Text that ends the reply stays visible after the fold, even when its message also calls a tool.
  - When the user opens or closes the work of a reply, it stays that way, even when later runs update the reply.
- **Render-Prop Override**: When `children` is provided as a function, the component delegates all layout to that function. The `messageElements` array is pre-built from the slot components, so custom layouts still benefit from slot customization.
- **Slot System**: Each slot prop accepts three forms -- a replacement component, a className string merged into the default, or a partial props object that extends the default component's props.
