Chat - Messages

Render conversation history as a virtualized, grouped, auto-scrolling message list.

Interactive playground

Toggle role, status, density, and grouping on a single ChatMessage bubble:

Group playground

ChatMessageGroup collapses consecutive messages from the same author into a single visual cluster:

List playground

ChatMessageList virtualizes rendering, manages auto-scroll, and can insert opt-in dividers between days:

The ChatMessage data model

Every message in the chat system is represented by the ChatMessage interface:

import type { ChatMessage } from '@mui/x-chat/headless';

A ChatMessage has the following shape:

author.id is the canonical identity key for message rendering. If you pass members, currentUser, or active conversation participants, chat components use that id to enrich missing display names and avatars at render time.

If your message model stores author identity somewhere else, provide getMessageAuthorId, getMessageAuthorDisplayName, and getMessageAuthorAvatarUrl on ChatProvider, ChatRoot, or ChatBox to map that data into the built-in message primitives.

Message parts

The parts array is the core content model. Each part has a type discriminant that determines how it renders:

This part-based model means a single message can contain mixed content—for example, a text explanation followed by a code block and a source citation.

Message status lifecycle

Messages progress through a status lifecycle:

pending → sending → streaming → sent → read
                 \→ error
                 \→ cancelled

• pending—the message is queued but not yet dispatched to the adapter.
• sending—the message has been dispatched; waiting for the first response chunk.
• streaming—the assistant is actively generating tokens.
• sent—the response is complete.
• read—the recipient has seen the message. The runtime never infers this state; supply it from your data source or adapter. The meta slots render it as a double checkmark.
• error—the adapter encountered an error.
• cancelled—the user or application cancelled the response.

Import

import { ChatMessageList, ChatMessageGroup, ChatMessage } from '@mui/x-chat';

Component anatomy

Inside ChatBox, the message list renders a subtree of themed components:

ChatMessageList                     ← scrollable container
  MessageListDateDivider            ← date separator between message groups (opt-in)
  ChatMessageGroup                  ← groups consecutive same-author messages
    ChatMessage                     ← individual message row
      ChatMessageAvatar             ← author avatar
      ChatMessageContent            ← message bubble with part renderers
      ChatMessageMeta               ← timestamp, delivery status
      ChatMessageActions            ← hover action buttons

How messages render

The ChatMessageList component is the scrollable region that renders conversation history. It manages scroll behavior, overflow, padding, and a thin scrollbar by default.

Message groups

Consecutive messages from the same author are grouped together into a ChatMessageGroup. Within a group, only the first message displays the avatar, reducing visual repetition and making the conversation easier to scan. If no display name or avatar resolves for a message author, the UI omits those affordances instead of falling back to the role name.

See Message appearance for grouping configuration and demos.

Date dividers

When consecutive messages span different calendar dates, the message list can render a date divider between them. Dividers are disabled by default—enable them with the dateDivider feature flag:

<ChatBox adapter={adapter} features={{ dateDivider: true }} />

See Date divider and Message appearance for customization.

Auto-scrolling

The message list automatically scrolls to the bottom when the user sends a new message, when new assistant messages arrive, and during streaming.

See Scrolling for buffer configuration and scroll-to-bottom affordance.

Accessibility

The message list is a single Tab stop: a roving tabindex over the role="article" messages keeps only one message in the tab order at a time, so tabbing through the page never walks every message.

• Arrow Up / Arrow Down and Home / End move between messages.
• Enter drills into the focused message's links, copy buttons, and actions; Escape returns to the message.
• The scroller is a role="log" polite live region, and a visually hidden role="status" region announces streaming transitions ("Assistant is responding" / "Response complete") exactly once each.
• The thread, composer, and conversation list are exposed as labeled landmarks.

Set enableRovingFocus={false} on the message list to opt out, and use the useMessageContentTabIndex() hook from @mui/x-chat/headless to let custom interactive content participate.

See the complete model—including the drill-in lifecycle, per-list focus memory, and locale keys—on the Accessibility page and in Message list—Accessibility.

Standalone usage

When building a custom layout outside of ChatBox, render ChatMessageList inside ChatConversation within a ChatProvider. The demo below isolates the message surface with only the provider, an active conversation scope, a bounded frame, and the message list composition:

Message slots

Each slot inside the ChatMessage row has its own playground—iterate on a single surface at a time.

Avatar

The author avatar slot—falls back to initials when no avatarUrl is set.

Author label

Displays the author name above grouped messages.

Content

The bubble interior—renders markdown, code fences, and tool or source parts.

Meta

External timestamp and delivery status, used by compact bubbles.

Inline meta

Telegram-style timestamp and status flowing inside the bubble.

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

• <ChatMessageAuthorLabel />
• <ChatMessageAvatar />
• <ChatMessageContent />
• <ChatMessageGroup />
• <ChatMessageInlineMeta />
• <ChatMessageList />
• <ChatMessageMeta />