Skip to content
Shortcut: /, ⌘K or Ctrl+K

Chat

Show one conversation with a message list, composer, inline chat window or chat drawer.

View as Markdown
Sample data
@polymorfa/react

Customize

Appearance
colorPrimary
colorBackground
colorForeground
colorMuted
colorBorder
colorDanger
colorSuccess
Props

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.

ReactWeb ComponentRenders
MessageListpmfa-message-listThe message log: bubbles, attachments, reply quotes, date separators and delivery status.
ComposeBoxpmfa-compose-boxThe composer: text field, emoji picker, attachments, voice notes and quick replies.
ChatWindowpmfa-chat-windowAn inline thread with a header, message list and composer. No close action.
ChatDrawerpmfa-chat-drawerThe same thread in a side drawer with a title and close button.

Controllers#

The components render state from two controllers in @polymorfa/browser:

  • ConversationController loads history, follows live updates and sends messages optimistically. It reads from a data source with load, subscribe and send methods, which you implement against your own storage or route.
  • MessageComposerController holds the draft text, attachments and reply target. Create its actions with createConversationComposerActions(), 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.
TSX
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#

TSX
<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#

TSX
<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#

TSX
<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:

TypeScript
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());
HTML
<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#

  • controllerController

    ConversationController for the list, window and drawer; MessageComposerController for the compose box.

    Elements All

  • configuration{ appearance?, locale?, stylesheet? }

    Appearance, text and extra CSS for this element.

    Elements All

  • composerControllerMessageComposerController

    Renders the built-in composer.

    Elements pmfa-chat-window, pmfa-chat-drawer

  • onReply(message) => void

    Shows Reply and receives each click.

    Elements pmfa-message-list, pmfa-chat-window, pmfa-chat-drawer

  • messageFilter(message) => boolean

    Hides messages from view.

    Elements pmfa-message-list, pmfa-chat-window, pmfa-chat-drawer

  • quickRepliesQuickReplyOption[]

    Options for the / menu.

    Elements pmfa-compose-box, pmfa-chat-window, pmfa-chat-drawer

  • conversationConversationController

    Resolves the reply banner.

    Elements pmfa-compose-box

  • messagesConversationMessage[]

    Resolves the reply banner without a controller.

    Elements pmfa-compose-box

  • openboolean

    Shows or hides the drawer.

    Elements pmfa-chat-drawer

  • openerHTMLElement

    Receives focus when the drawer closes.

    Elements pmfa-chat-drawer

Attributes#

  • heading

    Title text.

    Elements pmfa-chat-window, pmfa-chat-drawer

  • replyable

    Shows Reply on every message.

    Elements pmfa-message-list, pmfa-chat-window, pmfa-chat-drawer

    Default Off

  • autofocus

    Moves focus into a drawer that is already open when it connects.

    Elements pmfa-chat-drawer

    Default Off

  • placeholder

    Field placeholder.

    Elements Composer elements

    Default Locale text

  • attachments

    false hides the attach button, drop and paste.

    Elements Composer elements

    Default true

  • accept

    File types for the single file picker.

    Elements Composer elements

  • attachment-kinds

    Space-separated image, video, audio, document for the named picker.

    Elements Composer elements

  • multiple

    false allows one file at a time.

    Elements Composer elements

    Default true

  • emoji

    false hides the emoji button.

    Elements Composer elements

    Default true

  • voice-notes

    false hides the microphone.

    Elements Composer elements

    Default true

  • voice-note-auto-send

    false keeps a finished recording in the composer.

    Elements Composer elements

    Default true

  • max-rows

    Rows 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.

EventElementsdetailWhen
pmfa-replypmfa-message-list, pmfa-chat-window, pmfa-chat-drawerThe messageReply is selected.
pmfa-quick-replyComposer elementsThe optionA quick reply is inserted.
pmfa-closepmfa-chat-drawerThe close button or Escape is pressed.
pmfa-state-changeAllThe controller snapshotThe controller's state changes.
pmfa-renderAllThe 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.