Chat - Message Appearance

Control the visual presentation of messages — grouping, date dividers, avatars, timestamps, and layout variants.

This page covers the visual aspects of how messages are displayed in the message list. For message content rendering (text, files, code blocks), see the Message Parts section.

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.

The grouping window defaults to 5 minutes (300,000 ms). Messages from the same author that arrive within this window are placed in the same group. Customize it through slotProps:

Grouping is based on:

• Author identity (user ID)
• Author role fallback when no explicit author ID exists
• An adjustable time window in milliseconds

Date dividers

When consecutive messages span different calendar dates, a date divider is rendered automatically between them. The divider shows a localized date string and is styled as a centered label with horizontal rules.

Customize the date format through slotProps:

Avatars

The ChatMessageAvatar component renders the author's avatar for the first message in each group. Avatars are sourced from the ChatUser.avatarUrl field on the message's author.

Within a group, subsequent messages omit the avatar entirely — the component returns null rather than rendering a placeholder. If no avatarUrl is set on the author and no custom avatar slot is provided, the avatar is also omitted for the first message in the group.

Timestamps and metadata

ChatMessageMeta renders metadata below each message: a streaming progress bar while the message is being streamed, a delivery status label (sent or read) for outgoing messages, an "edited" label when message.editedAt is set, and a timestamp derived from the createdAt field on ChatMessage.

In the default layout, timestamps appear below the message bubble, aligned to the same side as the bubble (right for user messages, left for assistant messages).

Component anatomy

Inside ChatBox, the message list renders this component tree:

ChatMessageList                     ← scrollable container
  ChatDateDivider                   ← date separator between groups
  ChatMessageGroup                  ← groups consecutive same-author messages
    ChatMessage                     ← individual message row
      ChatMessageAvatar             ← author avatar
      ChatMessageContent            ← message bubble with part renderers
      ChatMessageMeta               ← timestamp, delivery status, streaming progress, edited label
      ChatMessageActions            ← hover action buttons

Compact variant

Set variant="compact" on ChatBox to switch to a dense, messenger-style layout with no bubbles, left-aligned messages, and group header timestamps.

See Variants & Density for full details, a comparison table, and interactive demos.

Density

The density prop controls the vertical spacing between messages independently of the variant. Three values are available: compact, standard (default), and comfortable.

See Variants & Density for interactive density demos and guidance on combining variant and density.

Slots

The following slots are available for customization through ChatBox:

See also

• Message list for scrolling behavior, auto-scroll configuration, and history loading
• Message Actions for the hover action menu on messages
• Loading & Empty States for skeleton and empty state display

API

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

• <ChatDateDivider />
• <ChatMessageAuthorLabel />
• <ChatMessageAvatar />
• <ChatMessageGroup />
• <ChatMessageInlineMeta />
• <ChatMessageMeta />