Messages
The message system handles rendering, grouping, timestamps, reactions, replies, and more. Pass an array of ChatMessageData to ChatMessages and everything is handled automatically.
Basic Messages
The simplest usage: pass messages and a current user. Outgoing messages (matching currentUser.id) align right, incoming messages align left.
Message Grouping
Consecutive messages from the same sender within a configurable time window (default: 2 minutes) are automatically grouped. Grouped messages share an avatar and have tighter spacing.
Reply-to Quotes
Add a replyTo object to any message to show a quoted reply above the message bubble.
System Messages
Set isSystem: true on a message to render it as a centered system notification. These are used for events like "user joined" or "conversation created".
Date Separators
Date separators are automatically inserted between messages from different days. No configuration needed — just pass messages with different date timestamps and the separators appear.
Message Data Shape
Each message is a ChatMessageData object with these key fields:
| Field | Type | Description |
|---|---|---|
id | string | Unique message identifier |
senderId | string | ID of the sender (matched against currentUser.id) |
senderName | string | Display name |
text | string? | Message text content |
timestamp | Date | number | When the message was sent |
status | "sending" | "sent" | "delivered" | "read" | "failed" | Delivery status (outgoing only) |
replyTo | { id, senderName, text }? | Quoted reply reference |
reactions | { emoji, userIds, count }[]? | Reaction data |
isSystem | boolean? | Render as centered system event |
senderAvatar | string? | URL for the sender's avatar image |
readBy | { userId, name, avatar? }[]? | Users who have read this message |
systemEvent | { type, data? }? | Structured data for system event messages |
isPinned | boolean? | Show pin indicator |
isEdited | boolean? | Show edited label |