# Message (/docs/agent-ui/components/message)

Use a message for each turn in a conversation, from the person or the assistant. Its toolbar holds the actions you handle, and shows once the message is done streaming.

<Example caption="Press Edit on the question to change it, then press Enter to save or Escape to cancel. Press Regenerate on the reply to add a response, and the arrows to switch between them.">
<Basic />

```tsx
"use client";
import { useState } from "react";
import { KindToolbar, KindToolbarButton } from "@/components/ui/internal/toolbar";
import {
  Message,
  MessageBranch,
  MessageBranchLabel,
  MessageBranchNext,
  MessageBranchPrevious,
  MessageContent,
  MessageCopy,
  MessageEdit,
  MessageEditor,
  MessageRegenerate,
  MessageToolbar,
} from "@/components/ui/message";

const replies = [
  "Retry with exponential backoff, and cap the number of attempts.",
  "Queue the request and retry it from a background job.",
  "Fail fast and let the caller decide whether to retry.",
];

export default function MessageExample() {
  const [question, setQuestion] = useState("How should the client handle a flaky upstream?");
  const [branches, setBranches] = useState({ index: 0, count: 2 });
  const reply = replies[branches.index] as string;

  return (
    <div className="flex w-full max-w-xl flex-col gap-6">
      <Message
        aria-label="User message"
        messageRole="user"
        text={question}
        onEdit={(text) => setQuestion(text)}
      >
        <MessageContent>{question}</MessageContent>
        <MessageEditor />
        <MessageToolbar>
          <KindToolbar aria-label="Message actions">
            <MessageCopy>
              <KindToolbarButton aria-label="Copy" />
            </MessageCopy>
            <MessageEdit>
              <KindToolbarButton aria-label="Edit" />
            </MessageEdit>
          </KindToolbar>
        </MessageToolbar>
      </Message>
      <Message
        aria-label="Assistant message"
        messageRole="assistant"
        text={reply}
        branchIndex={branches.index}
        branchCount={branches.count}
        onBranchChange={(index) => setBranches({ ...branches, index })}
        onRegenerate={() => {
          const count = Math.min(branches.count + 1, replies.length);
          setBranches({ index: count - 1, count });
        }}
      >
        <MessageContent>{reply}</MessageContent>
        <MessageToolbar>
          <MessageBranch>
            <MessageBranchPrevious />
            <MessageBranchLabel />
            <MessageBranchNext />
          </MessageBranch>
          <KindToolbar aria-label="Message actions">
            <MessageCopy>
              <KindToolbarButton aria-label="Copy" />
            </MessageCopy>
            <MessageRegenerate>
              <KindToolbarButton aria-label="Regenerate" />
            </MessageRegenerate>
          </KindToolbar>
        </MessageToolbar>
      </Message>
    </div>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/message
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/message-web
```

## Composition [#composition]

```text
Message
├── MessageAvatar
├── MessageContent
├── MessageEditor
└── MessageToolbar
    ├── MessageBranch
    │   ├── MessageBranchPrevious
    │   ├── MessageBranchLabel
    │   └── MessageBranchNext
    └── KindToolbar
        ├── MessageCopy
        ├── MessageRegenerate
        └── MessageEdit
```

The content holds the message, rendered however you like, for example with Markdown. The editor is a text area that takes the content's place while a user message is edited. `MessageCopy`, `MessageRegenerate` and `MessageEdit` each wrap a `KindToolbarButton` and give it its icon and action. The toolbar they sit in is one Tab stop, and the arrow keys move between its buttons. `MessageBranch` switches between responses, with a label like "2 of 3".

## Usage [#usage]

### Role and Status [#role-and-status]

Set `messageRole` to `user` or `assistant`. A user message sits at the end of the line in a bubble. Set `status` as a response arrives: the toolbar stays hidden while it's `submitted` or `streaming`, and fades in when the message settles.

### Copy [#copy]

Pass the message's `text`, which copy writes to the clipboard. The icon turns into a check for two seconds, and the message tells screen readers "Copied" politely, or "Copy failed". To copy something else, like Markdown converted to HTML, cancel `onCopy` and write it yourself.

### Regenerate and Edit [#regenerate-and-edit]

Each action shows only when you handle it. Pass `onRegenerate` to show regenerate. Pass `onEdit` to show edit on a user message: pressing it swaps the content for the editor, filled with `text`. Enter or moving focus away saves, and Escape cancels. `onEdit` gets the new text, and isn't called when the text didn't change.

### Responses [#responses]

When a message has more than one response, pass `branchCount` and `branchIndex`, from 0. The previous and next buttons call `onBranchChange` with the index they ask for, and the message shows it once you pass that `branchIndex` back:

```tsx
<Message
  text={replies[index]}
  branchIndex={index}
  branchCount={replies.length}
  onBranchChange={(next) => setIndex(next)}
>
  <MessageContent>{replies[index]}</MessageContent>
  <MessageToolbar>
    <MessageBranch>
      <MessageBranchPrevious />
      <MessageBranchLabel />
      <MessageBranchNext />
    </MessageBranch>
  </MessageToolbar>
</Message>
```

The switcher shows only when `branchCount` is more than 1.

## API Reference [#api-reference]

### MessageOptions

| Prop              | Type                                                                                                | Description                                                                                                |
| ----------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `messageRole?`    | `"assistant" \| "system" \| "user"`                                                                 | Who wrote it. Not `role`, which is the element's ARIA role. Default: `"assistant"`                         |
| `status?`         | `"aborted" \| "complete" \| "error" \| "streaming" \| "submitted"`                                  | Where the response is. The toolbar shows once it's no longer submitted or streaming. Default: `"complete"` |
| `text?`           | `string \| undefined`                                                                               | What `copy` writes and editing starts from. Default: `""`                                                  |
| `branchIndex?`    | `number \| undefined`                                                                               | The response shown, from 0. Change it in `onBranchChange`. Default: `0`                                    |
| `branchCount?`    | `number \| undefined`                                                                               | How many responses there are. The switcher shows above 1. Default: `1`                                     |
| `onBranchChange?` | `((index: number, details: ChangeDetails<MessageBranchChangeReason>) => void) \| undefined`         | Called with the index of the response someone asks for. Pass it back as `branchIndex` to show it.          |
| `onCopy?`         | `((text: string, details: ChangeDetails<"copy-press" \| "imperative">) => void) \| undefined`       | Called before `text` is copied. Cancel it to copy something else yourself.                                 |
| `onRegenerate?`   | `((text: string, details: ChangeDetails<"regenerate-press" \| "imperative">) => void) \| undefined` | Called to ask for a new response. Shows the regenerate action while set.                                   |
| `onEdit?`         | `((text: string, details: ChangeDetails<InlineEditReason>) => void) \| undefined`                   | Called with the new text when someone saves an edit. Shows the edit action on user messages while set.     |
| `motion?`         | `"auto" \| "none" \| "reduced"`                                                                     | `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`                                               |

### Agent [#agent]

An agent connected with `createAgent` reads each message's `status`, `branchIndex` and `branchCount`. It can run these actions, and press the buttons like a person would. Each one is offered only while the message shows it:

### MessageAgentActions

| Prop         | Type                                                    | Description                                                                                     |
| ------------ | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `copy`       | `(event?: Event) => Promise<boolean>`                   | Copies `text` and resolves with whether it worked.                                              |
| `regenerate` | `((event?: Event) => void) \| undefined`                | Calls `onRegenerate`. Offered once the message settles, while `onRegenerate` is set.            |
| `edit`       | `((event?: Event) => void) \| undefined`                | Starts editing in place. Offered once a user message with `onEdit` settles.                     |
| `setBranch`  | `((index: number, event?: Event) => void) \| undefined` | Asks `onBranchChange` for the response at an index, from 0. Offered when there's more than one. |

<Caption>
Runs in React and Web Components. On `<kind-message>`, each prop is a kebab-case attribute, so `messageRole` is `message-role`, and each callback is a lowercase event, so `onBranchChange` fires `branchchange`. `onCopy` fires `messagecopy`, since `copy` is a native event. Add the `can-regenerate` and `can-edit` attributes to offer those actions, which then fire `regenerate` and `edit`.
</Caption>