Chat
Show one conversation with a message list, composer, inline chat window or chat drawer.
Customize
Explore with sample data. Messages, calls and template actions stay in this demo.
The chat components show one conversation. Use them when you already have a screen for choosing conversations; use <Inbox/> for the complete list-and-thread layout.
| React | Web Component | Renders |
|---|---|---|
MessageList | pmfa-message-list | The message log: bubbles, attachments, reply quotes, date separators and delivery status. |
ComposeBox | pmfa-compose-box | The composer: text field, emoji picker, attachments, voice notes and quick replies. |
ChatWindow | pmfa-chat-window | An inline thread with a header, message list and composer. No close action. |
ChatDrawer | pmfa-chat-drawer | The same thread in a side drawer with a title and close button. |
Controllers#
The components render state from two controllers in @polymorfa/browser:
ConversationControllerloads history, follows live updates and sends messages optimistically. It reads from a data source withload,subscribeandsendmethods, which you implement against your own storage or route.MessageComposerControllerholds the draft text, attachments and reply target. Create its actions withcreateConversationComposerActions(), passing the conversation and your upload function, so the list and composer share one history. The upload function is yours: it turns the picked file into a hosted attachment and reports progress.
import {
ConversationController,
MessageComposerController,
createConversationComposerActions,
} from "@polymorfa/browser";
import { ChatWindow, PolymorfaProvider } from "@polymorfa/react";
const conversation = new ConversationController(source);
const composer = new MessageComposerController(
createConversationComposerActions(conversation, uploadFile),
);
await conversation.load();
<PolymorfaProvider>
<ChatWindow
controller={conversation}
composerController={composer}
header={<h2>Customer support</h2>}
/>
</PolymorfaProvider>;Create controllers once per conversation, outside render, and dispose them when the conversation is removed. Each component also accepts a createController factory; controllers it creates are disposed with the component. Controllers you pass in are never disposed for you.
A failed send keeps its text, attachments and reply target, and the message shows Retry. Resubmitting an unchanged draft reuses the same client operation ID, so your send route can treat it as idempotent.
MessageList#
<MessageList controller={conversation} onReply={(message) => setReplyTo(message)} />All 8 MessageList props, with types, defaults and a live preview, are on the MessageList page.
Consecutive messages from the same side are grouped. "Today", "Yesterday" or a localized date separates days. Outbound messages show a pending, sent or failed icon, and a failed message offers Retry. Images render as lazy thumbnails; other files render as a card with the name, size and a link. Only https:, http: and blob: URLs become links or images. Selecting a reply quote scrolls to and focuses the quoted message.
ComposeBox#
<ComposeBox
controller={composer}
placeholder="Reply to Casey"
quickReplies={[{ id: "thanks", shortcut: "thanks", text: "Thanks for reaching out!" }]}
/>All 20 ComposeBox props, with types, defaults and a live preview, are on the ComposeBox page.
The toolbar reads, in order: startActions, the emoji button, the attach button, the message field, endActions, then the microphone or the send button. Send replaces the microphone once there is text or an uploaded attachment. Files can be attached with the button, by pasting or by dropping them on the composer. Pending files show upload progress, a failed state and a remove button. A rejected file, such as one over the size limit, shows as the composer error.
Voice notes record as audio/webm, audio/ogg or audio/mp4, depending on the browser. While recording, a bar shows the elapsed time, the input level, a delete button and a send button. The microphone is released when recording ends or the composer unmounts.
The emoji set is built in and needs no network. Recent emoji are kept in localStorage when it is available.
ChatWindow#
All 13 ChatWindow props, with types, defaults and a live preview, are on the ChatWindow page.
ChatDrawer#
<ChatDrawer
open={open}
onClose={() => setOpen(false)}
conversation={conversation}
composerController={composer}
title="Casey Rivera"
/>All 17 ChatDrawer props, with types, defaults and a live preview, are on the ChatDrawer page.
Web Components #
Register the elements with definePolymorfaElements() or defineChatElements(), then assign controllers as properties:
import {
ConversationController,
MessageComposerController,
createConversationComposerActions,
} from "@polymorfa/browser";
import { defineChatElements } from "@polymorfa/elements";
defineChatElements();
const conversation = new ConversationController(source);
const composer = new MessageComposerController(
createConversationComposerActions(conversation, uploadFile),
);
const drawer = document.querySelector("pmfa-chat-drawer");
drawer.controller = conversation;
drawer.composerController = composer;
drawer.addEventListener("pmfa-close", () => drawer.remove());<pmfa-chat-drawer heading="Casey Rivera" replyable></pmfa-chat-drawer>
<pmfa-compose-box placeholder="Reply to Casey" voice-notes="false">
<button slot="end-actions" type="button">Templates</button>
</pmfa-compose-box>Properties#
controllerControllerConversationControllerfor the list, window and drawer;MessageComposerControllerfor the compose box.Elements All
configuration{ appearance?, locale?, stylesheet? }Appearance, text and extra CSS for this element.
Elements All
composerControllerMessageComposerControllerRenders the built-in composer.
Elements
pmfa-chat-window,pmfa-chat-draweronReply(message) => voidShows Reply and receives each click.
Elements
pmfa-message-list,pmfa-chat-window,pmfa-chat-drawermessageFilter(message) => booleanHides messages from view.
Elements
pmfa-message-list,pmfa-chat-window,pmfa-chat-drawerquickRepliesQuickReplyOption[]Options for the
/menu.Elements
pmfa-compose-box,pmfa-chat-window,pmfa-chat-drawerconversationConversationControllerResolves the reply banner.
Elements
pmfa-compose-boxmessagesConversationMessage[]Resolves the reply banner without a controller.
Elements
pmfa-compose-boxopenbooleanShows or hides the drawer.
Elements
pmfa-chat-draweropenerHTMLElementReceives focus when the drawer closes.
Elements
pmfa-chat-drawer
Attributes#
headingTitle text.
Elements
pmfa-chat-window,pmfa-chat-drawerreplyableShows Reply on every message.
Elements
pmfa-message-list,pmfa-chat-window,pmfa-chat-drawerDefault Off
autofocusMoves focus into a drawer that is already open when it connects.
Elements
pmfa-chat-drawerDefault Off
placeholderField placeholder.
Elements Composer elements
Default Locale text
attachmentsfalsehides the attach button, drop and paste.Elements Composer elements
Default
trueacceptFile types for the single file picker.
Elements Composer elements
attachment-kindsSpace-separated
image,video,audio,documentfor the named picker.Elements Composer elements
multiplefalseallows one file at a time.Elements Composer elements
Default
trueemojifalsehides the emoji button.Elements Composer elements
Default
truevoice-notesfalsehides the microphone.Elements Composer elements
Default
truevoice-note-auto-sendfalsekeeps a finished recording in the composer.Elements Composer elements
Default
truemax-rowsRows the field grows to before it scrolls.
Elements Composer elements
Default
8
Composer elements are pmfa-compose-box, pmfa-chat-window and pmfa-chat-drawer. Place your own buttons in the compose box toolbar with slot="start-actions" and slot="end-actions".
Events#
All events bubble and cross the shadow boundary.
| Event | Elements | detail | When |
|---|---|---|---|
pmfa-reply | pmfa-message-list, pmfa-chat-window, pmfa-chat-drawer | The message | Reply is selected. |
pmfa-quick-reply | Composer elements | The option | A quick reply is inserted. |
pmfa-close | pmfa-chat-drawer | The close button or Escape is pressed. | |
pmfa-state-change | All | The controller snapshot | The controller's state changes. |
pmfa-render | All | The element finishes rendering. |
Messages whose object has not changed keep their DOM nodes across updates, and the composer keeps its text field. Focus, scroll position and the live region stay in place while the conversation changes.
Accessibility#
- The message list is a log region. Status changes are announced politely.
- Enter sends and Shift+Enter adds a line, except while an input method is composing text.
- The quick reply field follows the ARIA combobox pattern: Up and Down move, Enter or Tab inserts, and Escape closes the list.
- In the emoji picker, arrow keys move through the grid and Escape closes it and returns focus to the button. On screens 600px wide or less it opens as a bottom sheet.
- Recording start and stop are announced. A denied microphone shows a localized error.
- Every composer button is at least 40px.
- The drawer is a non-modal dialog labelled by its title. When it opens, focus moves to the message field (or the close button). When it closes, focus returns to the element that had it. Escape closes it only when pressed inside the drawer. The chat window has no close action and does not capture Escape.