# Chat Message

A single message bubble on the indigo tint, aligned right for the user and left for the assistant.

- Category: AI & Agents
- Page: https://wunderui.com/components/chat-message
- Tier: Core and Pro

## Install

Chat Message ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { ChatMessage, ChatConversation } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { Avatar, AvatarFallback, ChatConversation, ChatMessage } from "@wunderui/react"

export function Thread() {
  return (
    <div role="log" aria-label="Conversation with Claude">
      <ChatConversation>
        <ChatMessage role="user" avatar={<Avatar><AvatarFallback>NL</AvatarFallback></Avatar>}>
          Summarize the Q3 report.
        </ChatMessage>
        <ChatMessage role="assistant">Revenue grew 12% quarter over quarter.</ChatMessage>
      </ChatConversation>
    </div>
  )
}
```

Expected result: You see two bubbles on the indigo tint: the question on the right with the initials NL beside it, and the answer on the left.

## When to use

### Use Chat Message for

- One turn in a chat with an assistant, a support bot or a teammate
- A conversation that grows at the bottom, with replies that stream in
- Messages that carry text, lists and code blocks

### Use something else

- [Chat Message Actions](https://wunderui.com/components/chat-message-actions) for the copy, retry and rating buttons under a finished reply
- [Chat Loader](https://wunderui.com/components/chat-loader) for the three dots while the assistant has not started its answer
- [Chat Tool](https://wunderui.com/components/chat-tool) for a tool call the agent makes while it works, with its status and result

## Behavior

What the message does with its role, its style, its width and assistive technology.

- **Role:** The user role reverses the row, so the avatar and bubble sit on the right, and flattens the top right corner. The assistant role keeps the row and flattens the top left corner.
- **Style:** The default style puts both bubbles on the indigo tint. The distinct style makes the user bubble neutral and gives the assistant plain text at full width, as many assistants do.
- **Width:** The bubble is as wide as its content and at most 75% of the row, and text wraps inside it. The distinct assistant can shrink, so long lines and code never widen the row.
- **State:** The message has no state prop. Pass the loader, the partial text or the finished text as children, and mark the log busy while a reply streams.
- **Live region:** The message announces nothing itself. The polite log region around it reads each new message when the screen reader is idle, and a busy flag holds the reading until the reply is complete.
- **Focus:** A message is text and takes no focus. Buttons inside it, such as the actions, are reached with Tab in reading order.
- **Motion:** The library adds no animation, so there is nothing to reduce. If you animate a new message in, fade and move it over a base duration and turn it off for reduced motion.

## Anatomy

- `ChatConversation`: Stacks the messages of a chat in a column with a 16 px gap. It is a plain div, so put the log region around it, not on it.
- `ChatMessage`: One turn of the chat: a row with an optional avatar and a bubble. The user role puts the avatar and bubble on the right and the assistant role on the left, and a variant picks the bubble style.
- `Avatar`: The optional avatar before the bubble, an Avatar or Agent Avatar. It does not shrink and stays at the top of the row, also when the bubble grows tall.
- `Bubble`: The box around the message, up to 75% of the row wide, with 14 px text. By default it is indigo tint with one flat corner, and the distinct style makes the assistant plain full-width text.

## Best practices

### When to use

- Use ChatMessage for one turn of a chat. Group the turns in a ChatConversation and put that in a log region.

### Do

- Set the role on every message, since it flips the row and the flat corner. Both roles share the indigo tint by default, so give the assistant an avatar as well.
- Wrap the conversation in a log region with an aria-label. A log is a polite live region, so each message you add is announced without moving focus.
- Mark the log busy while a reply streams and clear it when the reply is complete, so a screen reader that honours it reads the answer once instead of word by word.
- Show the loader first and the growing text after it, never both at once, and show the actions only when the reply is complete.
- Keep what arrived when a reply breaks off. Add a status line that says what happened and a button that asks again.

### Don't

- Don't put wide content into the bubble. It wraps at 75% of the row, so show a long table or a document in a panel next to the chat.
- Don't recolour the bubbles to tell the sender. The default style uses one tint for both on purpose, and the role, the side and the avatar show who is speaking.
- Don't announce every streamed word. Without the busy flag a polite region queues each change, so hold it back while the reply grows.

## API reference

### ChatMessage

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | ReactNode |  | What the bubble holds: text, a list, a code block, the loader or the actions. Swap it as the reply goes from pending to streaming to complete. |
| role* | "user" \| "assistant" |  | Who sent the message. `user` puts the row on the right and flattens the top right corner, `assistant` puts it on the left and flattens the top left corner. |
| avatar | ReactNode |  | An element shown before the bubble, usually an Avatar. For the user it sits on the right of the bubble. |
| className | string |  | Extra classes for the row, for example `min-w-0 flex-1` when the message sits in a flex row of its own. |
| footer | ReactNode |  | Sits under the bubble and shares its width, for example a sources disclosure or a time line. |
| maxWidth | CSSProperties["maxWidth"] |  | Widest the bubble may grow, for example `520` or `"85%"`. Without it the bubble stops at 75 % of the row. |
| tone | "neutral" \| "primary" |  | Colour of the user bubble. `primary` is the solid brand colour, `neutral` the muted grey. Without it the variant decides. |
| variant | "default" \| "distinct" \| "inverse" | "default" | `default` puts both bubbles on the indigo tint. `distinct` gives the user a neutral bubble and the assistant plain text at full width. |

### ChatConversation

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | ReactNode |  | The messages, in the order they were sent. |
| className | string |  | Extra classes for the column, for example `w-full max-w-2xl` to limit the width of the thread. |

## Examples

### Avatar: none, one for the assistant, or one for each side

### Content: a short line, a long paragraph, a list with code

### State: waiting, streaming, complete

### Primary bubble, attachment above, sources underneath

## In context

### Conversation: a question, an answer with a list and code, and the actions

The actions sit under the finished bubble, in line with its left edge. The conversation is a log region, so new messages are announced politely.

### Live reply: the loader, the streamed words, then the actions

Press Ask again. The actions appear only once the reply is complete, Tab reaches the button and the four actions, and Enter or Space presses them.

### Outcome: a reply that broke off or was stopped

The bubble keeps what arrived, a status line says what happened and a button asks again. The loader never stays on after a failure.

## For AI agents

`get_component("chat-message")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
