Inbox
A complete inbox with a conversation list, chat thread and contact panel, or each part on its own.
CustomizeComposeBox
Offer file attachments: the attach button, drop and paste. Defaults to `true`. Turn it off when the composer's actions have no upload adapter.
File types the attach button offers, as for `<input accept>`.
Offer named file types. Omit to keep the single file picker.
Allow picking several files at once. Defaults to `true`.
Resolves the reply banner's quoted message.
Resolves the reply banner's quoted message without a controller.
Replaces the locale's `composer.placeholder`.
Rendered in the toolbar before the built-in buttons.
Rendered after the message field, before the send or mic button.
Show the emoji picker button. Defaults to `true`.
Show the voice note button. Defaults to `true` where the browser has `MediaRecorder` and `getUserMedia`.
Send a voice note as soon as it finishes uploading. Defaults to `true`.
Options for the "/" quick reply menu.
Called after a quick reply's text is inserted.
Rows the message field grows to before it scrolls. Defaults to 8.
React only: @polymorfa/elements has no element for InboxRecipe.
npm install @polymorfa/react@dev @polymorfa/browser@devimport { PolymorfaProvider, ConversationList, MessageList, ComposeBox, ContactPanel } from "@polymorfa/react";
const appearance = { theme: "light", variables: { colorPrimary: "#635bff" } };
export function ConversationListExample({ conversation, composer, inbox, selectedConversation }) {
return (
<PolymorfaProvider tokenEndpoint="/api/polymorfa/token" appearance={appearance}>
<style>{".inbox-recipe { display: grid; grid-template-columns: 220px minmax(0, 1fr) 240px; gap: 16px; }\n@media (max-width: 900px) { .inbox-recipe { grid-template-columns: 1fr; } }\n/* Composer row alignment until the UI Kit stylesheet includes it. */\n.pmfa-composer .pmfa-input { min-height: 40px; padding-block: max(4px, calc((40px - 1.45em - 2px) / 2)); }\n.pmfa-chat-window .pmfa-composer .pmfa-input { min-height: 44px; padding-block: max(4px, calc((44px - 1.4em - 2px) / 2)); }\n.pmfa-chat-window .pmfa-composer-row .pmfa-btn-icon { min-height: 44px; margin-block: 0; }\n@media (max-width: 600px) { .pmfa-composer .pmfa-input { min-height: 44px; padding-block: max(4px, calc((44px - 1.45em - 2px) / 2)); } }"}</style>
<div className="inbox-recipe">
<aside><ConversationList
controller={inbox}
title="Conversations"
search
drafts={{ sam: "Your order is ready." }}
/></aside>
<section>
<MessageList
controller={conversation}
/>
<ComposeBox
controller={composer}
attachments
accept="image/*,application/pdf"
attachmentKinds={["image", "document"]}
multiple
placeholder="Write a message…"
emoji
voiceNotes={false}
voiceNoteAutoSend={false}
quickReplies={[
{ id: "hello", shortcut: "hello", text: "Hi! How can I help?" }
]}
maxRows={8}
/>
</section>
<aside><ContactPanel
conversation={selectedConversation}
>
Customer since 2024
</ContactPanel></aside>
</div>
</PolymorfaProvider>
);
}Build an inbox from ConversationList, MessageList, ComposeBox and ContactPanel. Choose a component above to edit its props. The preview keeps the same sample conversation and attachment data while you change code frameworks.
Attachments in this demo use local Blob URLs. Your app supplies an upload adapter when creating its composer controller. See chat controllers.
For a preassembled layout, use Inbox. The installed release exposes its composer settings but does not accept a custom upload adapter through Inbox. Use the composed layout above when you need attachment uploads.
"use client";
import { Inbox, PolymorfaProvider } from "@polymorfa/react";
<PolymorfaProvider tokenEndpoint="/api/polymorfa/token">
<div style={{ height: 640 }}>
<Inbox title="Support" />
</div>
</PolymorfaProvider>;Data and permissions #
By default the inbox reads conversations and messages from your route's history routes, follows live updates from its events route, and sends with the client token. To read from somewhere else, pass any InboxDataSource as source. A data source lists conversations, returns a message source for each conversation, and can optionally load contacts and publish changes.
Controls follow the grant your route returns:
| Control | Permission |
|---|---|
| Conversation list and messages | read_messages |
| Live updates | subscribe_events |
| Composer | send_message |
| Contact panel | read_contact |
| Call button in the thread header | voip_place |
Without read_messages, the inbox shows its empty state. Without send_message, the thread is read-only and says so. Each hidden control logs one warning in development builds, for example <Inbox/>: composer hidden; the token lacks "send_message". Add it to allow in mint(). Production builds log nothing.
<pmfa-inbox> with a custom source and no client renders every control and leaves enforcement to your source.
Compose the inbox#
Combine ConversationList, MessageList, ComposeBox and ContactPanel when you need independent control of each piece. A shared conversation controller keeps the list and composer in sync. Supply the composer’s upload adapter to handle attachments.
Inbox props#
All 11 Inbox props, with types, defaults and a live preview, are on the Inbox page.
On narrow screens the inbox shows the list or the thread, with a Back button to return to the list.
ConversationList#
The inbox's list, usable on its own with an InboxController.
All 12 ConversationList props, with types, defaults and a live preview, are on the ConversationList page.
ConversationListView#
A controlled list for apps that load and change conversations themselves. Pass the rows and selection directly.
All 17 ConversationListView props, with types, defaults and a live preview, are on the ConversationListView page.
Row actions are pin, unpin, archive, unarchive, mark-read and mark-unread. Supply both actions and onAction to show them. A failed action shows an error and keeps the row's previous state. There is no built-in action transport.
The list has All, Unread, Drafts and Archived filters, sorts pinned rows first, and supports keyboard navigation with the arrow keys, Home and End.
ContactPanel#
All 7 ContactPanel props, with types, defaults and a live preview, are on the ContactPanel page.
The contact panel is React only. <pmfa-inbox> has the list and the thread.
pmfa-inbox#
clientPolymorfaClientDefaults to the client from
definePolymorfa().sourceInboxDataSourceReplaces the default route-backed source.
controllerInboxControllerDrives the inbox from outside.
configuration{ appearance?, locale?, stylesheet? }Appearance, text and extra CSS for this element.
| Event | detail | When |
|---|---|---|
pmfa-select | The conversation | A conversation row is selected. |
pmfa-render | The element finishes rendering. |
Accessibility#
- Conversation rows are buttons. The open row is marked with
aria-current. Arrow keys, Home and End move between rows. - Unread counts have a text label, such as "3 unread", not color alone.
- The contact panel toggle is labelled "Show contact details" or "Hide contact details".
- The composer and message list follow the chat accessibility behavior.