Chat
Chat is a messaging surface between people: a conversation log, delivery and
read receipts, editing and deleting a message within a time window, replies,
file attachments, and an optional conversation list. It is controlled — your app
owns the messages and talks to the server; the component shows them and reports
what the user does. It fills its container, so the same anatomy works inside a
Drawer, a Card, or any sized region of a page.
Usage
import { Chat } from '@takeoff-ui/react-spar';
<Chat>
<Chat.ConversationList>
<Chat.Conversation />
</Chat.ConversationList>
<Chat.Thread>
<Chat.Header>
<Chat.Title />
</Chat.Header>
<Chat.Pinned />
<Chat.Messages>
<Chat.Message>
<Chat.MessageActions />
</Chat.Message>
</Chat.Messages>
<Chat.Empty />
<Chat.Composer />
</Chat.Thread>
</Chat>
Chat.ConversationList and Chat.Thread are only needed for the split layout;
a single conversation uses the thread parts directly under Chat.
Playground
Send a message to watch it go from sending (clock) to sent (one tick), delivered (two ticks) and read (two coloured ticks). Hover one of your messages for Edit and Delete, or press ↑ in the empty field to edit your last message. Edits stay open for 15 minutes and deletes for an hour. Any message can be answered with Reply.
Data model
A message is a plain object; update it immutably when the server answers.
interface ChatMessage {
id: string;
senderId: string; // equals `currentUserId` for the user's own messages
text: string;
createdAt: Date | string | number;
editedAt?: Date | string | number; // shows "Edited"
deleted?: boolean; // shows "This message was deleted"
status?: 'sending' | 'sent' | 'delivered' | 'read' | 'failed';
attachments?: ChatAttachment[]; // the same entries Upload uses
replyTo?: { id: string; senderId?: string; text?: string }; // the message it answers
}
| You want to… | Do this |
|---|---|
| Send a message | Handle onSend(text): append it with status: 'sending', then move it to sent / delivered / read as the server reports. |
| Show whether the other side read it | Set the status of the user's own messages. read draws the coloured double tick. |
| Mark incoming messages read | Handle onRead(messages). It fires once per message when an unread incoming message is on screen while the page is visible. Tell the server, then set their status to read. It needs IntersectionObserver; without it nothing is reported. |
| Let users edit or delete for a while | Pass onEdit / onDelete and editWindow / deleteWindow in milliseconds. The actions disappear when the window closes, and an edit in progress ends with it. Enforce the same limit on the server. |
| Let users take back a delete | Deleted messages offer Undo for undoWindow (5 seconds by default) and onDelete runs only after it, or when the chat unmounts. Pass undoWindow={0} to delete at once. |
| Let users send files | Set allowAttachments on Chat.Composer. onSend(text, attachments) gets the files; put them on the message and update each one's status / progress, then its url, as it uploads. |
| Let users answer a message | Reply is on by default. onSend gets the answered message as details.replyTo; store { id, senderId, text } of it on the new message's replyTo. |
| Pin messages | Pass pinnedIds and onPinChange, and place Chat.Pinned under the header. |
| Show who is typing | Pass typing with the participant ids. |
| Load history | Set hasOlder and handle onLoadOlder; prepend the older messages. The reader stays on the same message. |
Conversation list
With a Chat.ConversationList the chat shows the list beside the thread. When
the chat is narrower than 640px — a drawer, a phone — it shows one pane at a
time: the list until a conversation is opened, then the thread with a back
button in its header. Drive the open conversation with conversationId and
onConversationChange, and swap messages with it.
In a Drawer
Chat takes the height of its container, so a Drawer.Body without padding is
enough. Escape leaves message editing without closing the drawer.
Group chat
With more than one other participant, incoming messages show their author's name and avatar. Consecutive messages from one person within five minutes are grouped.
Replies
Reply is in every message's menu while onSend is set
(allowReplies={false} turns it off). The composer then shows the message being
answered above the field, with a button (or Esc) to stop.
onSend(text, attachments, { replyTo }) hands it over; put a reference to it on
the new message's replyTo.
A reply quotes the original at the top of its bubble. While the original is in
messages, the quote shows it as it is now — edited or deleted — and pressing
the quote scrolls to it and highlights it for a moment. When it is not loaded,
the quote falls back to the senderId and text stored on replyTo.
Attachments
allowAttachments on Chat.Composer adds an attach button and takes files
dropped on the composer or pasted into it. They wait above the field, each with
a remove button, and go to onSend with the text — or on their own. accept,
maxFileSize and maxFileCount limit what the composer takes; onFilesReject
reports what it turned down, so you can tell the user.
A file is a ChatAttachment, the same entry
Upload uses. On a message, uploaded images
show as previews and other files as rows with a download button. A file that is
still uploading shows its progress, and a failed one says so. Here the upload is
simulated.
Message actions
A message's menu lists what applies to it, in this order:
- Reply — on by default while
onSendis set;allowReplies={false}turns it off. - Copy — on by default for messages with text;
allowCopy={false}turns it off. - Pin / Unpin — set
pinnedIdsandonPinChange.Chat.Pinnedshows the pinned messages in a bar: pressing it scrolls to the one shown and moves on to the one pinned before it. - Edit and Delete — on the user's own messages, with
onEdit/onDelete, while their windows are open.
Compose Chat.MessageActions inside Chat.Message to add your own items after
them — here Create task. The edit and delete windows are 30 seconds, so
those two disappear shortly after a message is sent.
Localization
Every visible string and accessible name comes from labels; locale formats
times and dates. {names}, {name} and {count} are placeholders. Set them
once for the whole app through TakeoffSparProvider's
components.Chat.defaultProps.labels.
Accessibility
- The log is a
role="log"region, so screen readers announce new messages. It is focusable for keyboard scrolling. - Delivery status icons carry a text alternative ("Sent", "Read", …).
- Enter sends, Shift+Enter adds a line, and Enter during an IME composition does not send.
- ↑ in an empty field edits your last editable message; Esc leaves editing. While editing, the field is named "Editing message".
- The message menu button sits next to the top of the bubble and appears on hover and keyboard focus. A right click on the bubble opens the same menu (unless text in it is selected, so it can still be copied), and on touch screens a long press opens it.
- Copy confirms with a "Copied" note under the message, which a polite status region also reads out.
- The pinned bar is a button named after the pinned message ("Pinned message · 2 of 3 …"); a pinned message's meta line carries a pin with the text "Pinned message".
- A quote is read as "In reply to" its author and text; when the original is loaded it is a button that scrolls to it. While answering, the field is named "Replying to" the author, and Esc stops answering.
- The attach button is named "Attach files", and the files waiting to be sent are a group named "Files to send", each with a remove button named after the file ("Remove report.pdf"). Files can also be dropped on the composer or pasted into the field.
- After Delete, focus moves to the message's Undo button; once the undo window ends, it moves on to the composer.
API Reference
Chat
Props
| Name | Type | Default | Description |
|---|---|---|---|
| messages | ChatMessage[] | - | The conversation, oldest first. |
| currentUserId | string | - | The signed-in user. Messages whose senderId matches are drawn as the user's own. |
| participants | ChatParticipant[] | - | Everyone in the conversation, for names and avatars. With more than one other participant the chat is drawn as a group: incoming messages show their author's name and avatar. |
| allowReplies | boolean | true | Reply in every message's menu, while onSend is set. The composer then shows what is being answered, and onSend gets it as details.replyTo — store it on the new message's replyTo. |
| pinnedIds | string[] | - | Ids of the pinned messages, oldest pin first. Pair with onPinChange. |
| allowCopy | boolean | true | Copy in the menu of every message with text. It also works in a readOnly or disabled chat, since it changes nothing. |
| editWindow | number | - | How long after createdAt a message can still be edited, in milliseconds. Leave it unset for no limit. The Edit action disappears once it passes. |
| deleteWindow | number | - | How long after createdAt a message can still be deleted, in milliseconds. Leave it unset for no limit. The Delete action disappears once it passes. |
| undoWindow | number | 5000 | How long a deleted message can still be restored, in milliseconds. Until then it shows as deleted with an Undo button, and onDelete is called when the time is up — or right away if the chat unmounts first. 0 calls onDelete at once. |
| typing | string[] | - | Ids of the participants who are typing right now. Shows the typing line at the end of the log. |
| hasOlder | boolean | - | Shows a Load older messages button at the top of the log. Scrolling to the top loads them too. |
| isLoadingOlder | boolean | - | Older messages are loading: the button shows a spinner and the log is marked busy. |
| conversationId | string | null | - | The open conversation (controlled), for chats with a Chat.ConversationList. null means none is open. Pair with onConversationChange. |
| defaultConversationId | string | null | - | The conversation open at first (uncontrolled). |
| disabled | boolean | - | Turns the composer and the message actions (except Copy) off, e.g. while offline. |
| readOnly | boolean | - | View-only conversation: no composer, and Copy is the only message action. |
| locale | string | the browser's locale | BCP 47 locale for times and dates, e.g. 'tr-TR'. |
| labels | Partial<ChatLabels> | - | Texts of the chat, e.g. a translation. Anything left out stays in English. |
| children | React.ReactNode | - | The parts: Chat.Header, Chat.Messages, Chat.Empty, Chat.Composer, and optionally Chat.ConversationList + Chat.Thread. |
| classNames | Partial<Record<"root", string>> | - | |
| slotProps | Partial<Record<"root", React.HTMLAttributes<HTMLElement>>> | - | |
| className | string | - | Appends custom classes to the root slot. |
Events
| Name | Type | Default | Description |
|---|---|---|---|
| onSend | (text: string, attachments: ChatAttachment[], details: ChatSendDetails) => void | - | Called when the user sends a message, with its trimmed text and the files added in the composer (Chat.Composer's allowAttachments). The text is empty when only files are sent. Each file carries a fresh id and its file; upload it and put it on the message as an attachment. |
| onEdit | (message: ChatMessage, text: string) => void | - | Called with the message and its new trimmed text when an edit is saved. Setting it turns on the Edit action for the user's own messages. |
| onDelete | (message: ChatMessage) => void | - | Called when the user deletes one of their messages, once undoWindow has passed without an undo. Setting it turns on the Delete action. |
| onRead | (messages: ChatMessage[]) => void | - | Called with incoming messages that are not 'read' yet once they are on screen while the page is visible — mark them read on the server and set their status to 'read'. A message is reported once. Needs IntersectionObserver; where it is missing (e.g. jsdom) nothing is reported, so mock it in tests. |
| onPinChange | (message: ChatMessage, pinned: boolean) => void | - | Called when the user pins or unpins a message. Setting it turns on Pin / Unpin in every message's menu; Chat.Pinned shows the pinned ones. |
| onRetry | (message: ChatMessage) => void | - | Called from the Retry button under a 'failed' message. The button is shown only when this is set. |
| onLoadOlder | () => void | - | Called to load older messages. Prepend them to messages; the reader's place in the log is kept. |
| onConversationChange | (id: string | null) => void | - | Called when the user opens a conversation, or goes back to the list (null). |
Data attributes
| Attribute | Applied when | Purpose |
|---|---|---|
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-layout | Always (single | split) | split while a Chat.ConversationList is mounted: list and thread side by side. |
| data-view | Always (list | thread) | Which pane a narrow split chat shows — the list until a conversation is open. |
| data-disabled | When disabled | Styling hook for the disabled state. |
| data-readonly | When readOnly | Styling hook for the view-only state. |
Chat.ConversationList
Data attributes
| Attribute | Applied when | Purpose |
|---|---|---|
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
Chat.Conversation
Props
| Name | Type | Default | Description |
|---|---|---|---|
| conversation | ChatConversation | - | The conversation this item opens. |
| classNames | Partial<Record<ChatConversationSlot, string>> | - | |
| slotProps | Partial<Record<ChatConversationSlot, React.HTMLAttributes<HTMLElement>>> | - | |
| className | string | - | Appends custom classes to the root slot. |
Data attributes
| Attribute | Applied when | Purpose |
|---|---|---|
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-selected | When it is the open conversation | Selected treatment; aria-current="true" is set too. |
| data-unread | When unreadCount is above zero | Unread treatment (bold title). |
Chat.Thread
Data attributes
| Attribute | Applied when | Purpose |
|---|---|---|
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
Chat.Header
Data attributes
| Attribute | Applied when | Purpose |
|---|---|---|
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
Chat.Title
Data attributes
| Attribute | Applied when | Purpose |
|---|---|---|
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
Chat.Pinned
Data attributes
| Attribute | Applied when | Purpose |
|---|---|---|
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
Chat.Messages
Data attributes
| Attribute | Applied when | Purpose |
|---|---|---|
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
Chat.Message
Props
| Name | Type | Default | Description |
|---|---|---|---|
| message | ChatMessage | - | The message this row renders. |
| children | React.ReactNode | - | Replaces the text inside the bubble. A composed Chat.MessageActions becomes the row's menu. |
| classNames | Partial<Record<ChatMessageSlot, string>> | - | |
| slotProps | Partial<Record<ChatMessageSlot, React.HTMLAttributes<HTMLElement>>> | - | |
| className | string | - | Appends custom classes to the root slot. |
Data attributes
| Attribute | Applied when | Purpose |
|---|---|---|
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-own | On the current user's messages | Aligns the row to the end and colours the bubble. |
| data-status | When the message has a status | Delivery state: sending | sent | delivered | read | failed. |
| data-deleted | When deleted, or deleted and waiting out undoWindow | Deleted-message treatment. |
| data-deleting | While a delete can still be undone | Dims the message until onDelete runs. |
| data-grouped | When it continues the previous message’s group | Tighter spacing; hides the repeated avatar. |
| data-editing | While the composer edits or answers it | Outlines the message the composer is working on. |
| data-pinned | When its id is in pinnedIds | Shows the pin in the meta line. |
| data-highlighted | For a moment after a quote jumps to it | Flashes the bubble so the eye finds it. |
Chat.MessageActions
Data attributes
| Attribute | Applied when | Purpose |
|---|---|---|
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
Chat.Empty
Data attributes
| Attribute | Applied when | Purpose |
|---|---|---|
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
Chat.Composer
Props
| Name | Type | Default | Description |
|---|---|---|---|
| value | string | - | The draft (controlled). Pair with onValueChange. |
| defaultValue | string | - | The draft at first (uncontrolled). |
| maxLength | number | - | Longest message the user can send. |
| placeholder | string | - | Placeholder of the text field. Defaults to labels.placeholder. |
| startContent | React.ReactNode | - | Controls before the text field, e.g. an attach button. |
| endContent | React.ReactNode | - | Controls between the text field and the send button, e.g. an emoji picker. |
| allowAttachments | boolean | - | Lets the user add files: an attach button, dropping files on the composer, and pasting them. They go to onSend with the text. |
| accept | string | - | File types the composer takes, as in an <input type="file"> accept, e.g. 'image/*,.pdf'. |
| maxFileSize | number | - | Largest file the composer takes, in bytes. |
| maxFileCount | number | - | Most files one message can carry. |
| classNames | Partial<Record<ChatComposerSlot, string>> | - | |
| slotProps | Partial<Record<ChatComposerSlot, React.HTMLAttributes<HTMLElement>>> | - | |
| className | string | - | Appends custom classes to the root slot. |
Events
| Name | Type | Default | Description |
|---|---|---|---|
| onValueChange | (value: string) => void | - | Called with the draft on every change, including when it is cleared after sending. |
| onFilesReject | (rejections: UploadRejection[]) => void | - | Called with the files the composer turned down (type, size or count) — the composer shows nothing for them, so tell the user, e.g. with a toast. |
Data attributes
| Attribute | Applied when | Purpose |
|---|---|---|
| data-slot="root" | Always | Stable selector for wrapper styling on the root slot. |
| data-editing | While a message is being edited | Editing treatment of the composer. |
| data-drag-state | While files are dragged over it (allowAttachments) | accept | reject — the drop-target treatment; reject for types outside accept or while editing. |
Type Definitions
| Name | Definition |
|---|---|
| ChatMessage | { id: string; senderId: string; text: string; createdAt: ChatTimestamp; editedAt?: ChatTimestamp; deleted?: boolean; status?: ChatMessageStatus; attachments?: ChatAttachment[]; replyTo?: ChatReply } |
| ChatParticipant | { id: string; name: string; avatar?: string | ReactNode } |
| ChatLabels | { conversations: string; back: string; messages: string; loadOlder: string; today: string; yesterday: string; typing: string; typingMany: string; jumpToLatest: string; newMessages: string; placeholder: string; send: string; save: string; editing: string; cancelEdit: string; messageActions: string; edit: string; delete: string; undo: string; edited: string; deleted: string; sending: string; sent: string; delivered: string; read: string; failed: string; retry: string; unread: string; copy: string; pin: string; unpin: string; pinned: string; pinnedPosition: string; copied: string; reply: string; replyingTo: string; cancelReply: string; inReplyTo: string; you: string; originalMessage: string; attach: string; attachments: string; removeAttachment: string; downloadAttachment: string; openAttachment: string; uploading: string; uploadFailed: string; uploadProgress: string } |
| ChatAttachment | { id: string; file?: File; name?: string; size?: number; type?: string; url?: string; thumbUrl?: string; status?: UploadFileStatus; progress?: number; error?: string } |
| ChatSendDetails | { replyTo?: ChatMessage } |
| ChatConversation | { id: string; title: string; avatar?: string | ReactNode; preview?: ReactNode; updatedAt?: ChatTimestamp; unreadCount?: number } |
| ChatConversationSlot | 'root' | 'avatar' | 'body' | 'title' | 'preview' | 'time' | 'unread' |
| ChatHeaderSlot | 'root' | 'back' |
| ChatPinnedSlot | 'root' | 'jump' | 'label' | 'text' | 'unpin' |
| ChatMessagesSlot | 'root' | 'viewport' | 'content' | 'loadOlder' | 'divider' | 'typing' | 'typingDots' | 'jump' |
| ChatMessageSlot | | 'root' | 'avatar' | 'body' | 'author' | 'bubble' | 'text' | 'meta' | 'time' | 'edited' | 'status' | 'retry' | 'undo' | 'attachments' | 'image' | 'quote' | 'quoteAuthor' | 'quoteText' | 'copied' | 'pinned' |
| ChatComposerSlot | 'root' | 'editing' | 'cancel' | 'replying' | 'cancelReply' | 'controls' | 'send' | 'upload' | 'attach' | 'attachments' |
| UploadRejection | | { file: File; code: 'file-invalid-type'; /** The |