Chat Message
ProOne turn of a conversation: a bubble for the user on the right, one for the assistant on the left.
Playground
Installation
Chat Message comes with WunderUI Core and Pro, in the package from your plan. See the plans.
Then import what you need:
import { ChatMessage, ChatConversation } from "@wunderui/react"Then use it:
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 for
- Chat Message Actions for the copy, retry and rating buttons under a finished reply
- Chat Loader for the three dots while the assistant has not started its answer
- Chat Tool for a tool call the agent makes while it works, with its status and result
Avatar
The avatar sits before the bubble, and on the right for the user. Give the assistant one, so the bubbles differ by more than the flat corner.
Content
The bubble grows with its content up to 75% of the row, then wraps. Lists and code blocks go inside as children.
Three things stand out in the Q3 report:
- Revenue: $1,842,000, up 12%
- New customers: 1,204
- Churn: 1.8%, down from 2.4%
const growth = (q3 - q2) / q2 // 0.12State
A reply is pending until the first word arrives, streams while it grows and is complete when done. The message has no state prop: swap its children, and wrap the conversation in a log region.
Newer props
tone="primary" makes the user bubble the solid brand colour, maxWidth caps it, and footer puts a sources line under a bubble inside the same width. variant="inverse" is the dark user bubble of support chats.
Primary bubble, attachment above, sources underneath
Behavior and motion
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
The figure marks a conversation with a user and an assistant message. The bubble is the inner box of ChatMessage.
- 1data-slot="chat-conversation"Optional
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.
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.
- 2Optional
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.
- 3
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
- 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.
- Do
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.
- Do
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.
- Do
Show the loader first and the growing text after it, never both at once, and show the actions only when the reply is complete.
- Do
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
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
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
One table per part. Neither part wraps a primitive, so these tables list every prop.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| children required | ReactNode | — | The messages, in the order they were sent. |
| className | string | — | Extra classes for the column, for example to limit the width of the thread. |
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| role required | "user" | "assistant" | — | Who sent the message. puts the row on the right and flattens the top right corner, 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. |
| variant | "default" | "distinct" | "inverse" | "default" | puts both bubbles on the indigo tint. gives the user a neutral bubble and the assistant plain text at full width. |
| children required | 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. |
| className | string | — | Extra classes for the row, for example 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 or . Without it the bubble stops at 75 % of the row. |
| tone | "neutral" | "primary" | — | Colour of the user bubble. is the solid brand colour, the muted grey. Without it the variant decides. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("chat-message")The full library index for assistants is at /llms.txt.