# CopilotChatUserMessage

> Component for displaying user-authored messages with branch navigation

## Overview [#overview]

`CopilotChatUserMessage` shows user-authored messages aligned to the right with optional branch navigation. The default message renderer formats content with `white-space: pre-wrap` to preserve line breaks. Branch navigation controls only render when `numberOfBranches` is greater than 1 and an `onSwitchToBranch` handler is provided. Users can then move between the alternative branches of the conversation.

[`CopilotChatMessageView`](/reference/components/CopilotChatMessageView) renders this component for each user message. For assistant messages, see [`CopilotChatAssistantMessage`](/reference/components/CopilotChatAssistantMessage).

## Import [#import]

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

## Props [#props]

<PropertyReference name="message" type="UserMessage" required>
  The user message object to render. Contains the message `content`, `id`, and
  `role`.
</PropertyReference>

<PropertyReference
  name="onEditMessage"
  type="(props: { message: UserMessage }) => void"
>
  Callback invoked when the user clicks the edit button. When not provided, the
  edit button is hidden from the toolbar.
</PropertyReference>

<PropertyReference
  name="onSwitchToBranch"
  type="(props: { message: UserMessage; branchIndex: number; numberOfBranches: number }) => void"
>
  Callback invoked when the user navigates to a different branch. Receives the
  target `branchIndex` and total `numberOfBranches`. The component renders the
  branch navigation controls only when you pass this callback and
  `numberOfBranches` is greater than 1.
</PropertyReference>

<PropertyReference name="branchIndex" type="number">
  The zero-based index of the currently active branch. Used by the branch
  navigation controls to display the current position.
</PropertyReference>

<PropertyReference name="numberOfBranches" type="number">
  The total number of available branches for this message. The component
  renders branch navigation only when this value is greater than 1 and you pass
  `onSwitchToBranch`.
</PropertyReference>

<PropertyReference name="additionalToolbarItems" type="React.ReactNode">
  Additional React elements appended to the toolbar alongside the default action
  buttons.
</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="messageRenderer" type="typeof CopilotChatUserMessage.MessageRenderer | string | Partial<React.ComponentProps<typeof CopilotChatUserMessage.MessageRenderer>>">
  Slot for the message content renderer. Defaults to `CopilotChatUserMessage.MessageRenderer`, which formats message text with `white-space: pre-wrap` to preserve whitespace and line breaks.

**As a replacement component:**

```tsx
<CopilotChatUserMessage
  message={msg}
  messageRenderer={({ content }) => (
    <div className="font-mono text-sm">{content}</div>
  )}
/>
```

**As a className:**

```tsx
<CopilotChatUserMessage message={msg} messageRenderer="text-lg font-medium" />
```

</PropertyReference>

<PropertyReference name="toolbar" type="typeof CopilotChatUserMessage.Toolbar | string | Partial<React.ComponentProps<typeof CopilotChatUserMessage.Toolbar>>">
  Slot for the action toolbar container. Defaults to `CopilotChatUserMessage.Toolbar`, which renders a horizontal row of action buttons below the message content.

**As a className:**

```tsx
<CopilotChatUserMessage
  message={msg}
  toolbar="opacity-0 group-hover:opacity-100 transition-opacity"
/>
```

</PropertyReference>

<PropertyReference
  name="copyButton"
  type="typeof CopilotChatUserMessage.CopyButton | string | Partial<React.ComponentProps<typeof CopilotChatUserMessage.CopyButton>>"
>
  Slot for the copy-to-clipboard button. Defaults to
  `CopilotChatUserMessage.CopyButton`. The button takes its tooltip from
  `CopilotChatLabels.userMessageToolbarCopyMessageLabel`.
</PropertyReference>

<PropertyReference
  name="editButton"
  type="typeof CopilotChatUserMessage.EditButton | string | Partial<React.ComponentProps<typeof CopilotChatUserMessage.EditButton>>"
>
  Slot for the edit button. Defaults to `CopilotChatUserMessage.EditButton`.
  The component renders the edit button only when you pass `onEditMessage`.
  The button takes its tooltip from
  `CopilotChatLabels.userMessageToolbarEditMessageLabel`.
</PropertyReference>

<PropertyReference name="branchNavigation" type="typeof CopilotChatUserMessage.BranchNavigation | string | Partial<React.ComponentProps<typeof CopilotChatUserMessage.BranchNavigation>>">
  Slot for the branch navigation controls. Defaults to `CopilotChatUserMessage.BranchNavigation`, which renders previous/next arrows and a branch counter (e.g., "2 / 3"). The component renders it only when `numberOfBranches` is greater than 1 and you pass `onSwitchToBranch`. A replacement component gets the active branch index as `currentBranch`, with `numberOfBranches`, `onSwitchToBranch`, and `message`.

**As a replacement component:**

```tsx
<CopilotChatUserMessage
  message={msg}
  numberOfBranches={3}
  branchIndex={1}
  onSwitchToBranch={handleSwitch}
  branchNavigation={({
    currentBranch = 0,
    numberOfBranches = 1,
    onSwitchToBranch,
    message,
  }) => (
    <div className="flex items-center gap-1 text-xs">
      <button
        onClick={() =>
          onSwitchToBranch?.({
            message,
            branchIndex: currentBranch - 1,
            numberOfBranches,
          })
        }
        disabled={currentBranch === 0}
      >
        Prev
      </button>
      <span>
        {currentBranch + 1} of {numberOfBranches}
      </span>
      <button
        onClick={() =>
          onSwitchToBranch?.({
            message,
            branchIndex: currentBranch + 1,
            numberOfBranches,
          })
        }
        disabled={currentBranch === numberOfBranches - 1}
      >
        Next
      </button>
    </div>
  )}
/>
```

</PropertyReference>

## Usage [#usage]

### Basic User Message [#basic-user-message]

```tsx
function UserBubble({ message }) {
  return <CopilotChatUserMessage message={message} />;
}
```

### With Edit Support [#with-edit-support]

```tsx
function EditableUserMessage({ message, onEdit }) {
  return (
    <CopilotChatUserMessage
      message={message}
      onEditMessage={({ message }) => onEdit(message)}
    />
  );
}
```

### With Branch Navigation [#with-branch-navigation]

```tsx
function BranchedUserMessage({
  message,
  branchIndex,
  totalBranches,
  onSwitch,
}) {
  return (
    <CopilotChatUserMessage
      message={message}
      branchIndex={branchIndex}
      numberOfBranches={totalBranches}
      onSwitchToBranch={({ branchIndex }) => onSwitch(branchIndex)}
    />
  );
}
```

### Customizing Appearance with Slots [#customizing-appearance-with-slots]

```tsx
function StyledUserMessage({ message }) {
  return (
    <CopilotChatUserMessage
      message={message}
      messageRenderer="bg-blue-600 text-white rounded-2xl px-4 py-2"
      toolbar="mt-1"
      onEditMessage={({ message }) => console.log("Edit:", message.id)}
      additionalToolbarItems={
        <button onClick={() => console.log("Pin:", message.id)}>Pin</button>
      }
    />
  );
}
```

### Full Edit and Branch Workflow [#full-edit-and-branch-workflow]

```tsx
function FullFeaturedUserMessage({ message, branches }) {
  const [currentBranch, setCurrentBranch] = useState(0);

  return (
    <CopilotChatUserMessage
      message={message}
      branchIndex={currentBranch}
      numberOfBranches={branches.length}
      onSwitchToBranch={({ branchIndex }) => setCurrentBranch(branchIndex)}
      onEditMessage={({ message }) => {
        // Open edit modal
        openEditModal(message);
      }}
    />
  );
}
```

## Behavior [#behavior]

- **Right-Aligned Layout**: User messages are rendered with right-aligned positioning to visually distinguish them from assistant messages.
- **Whitespace Preservation**: The default message renderer uses `white-space: pre-wrap`, so line breaks and spacing in the original message are preserved.
- **Conditional Branch Navigation**: The branch navigation controls are only rendered when both conditions are met: `numberOfBranches > 1` and `onSwitchToBranch` is provided. This prevents showing navigation for single-branch conversations.
- **Conditional Edit Button**: The edit button only appears in the toolbar when `onEditMessage` is provided.
- **Localized Labels**: Toolbar button tooltips are sourced from the nearest `CopilotChatConfigurationProvider`. See [`useCopilotChatConfiguration`](/reference/hooks/useCopilotChatConfiguration) for available label keys.
