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

Inbox

A complete inbox with a conversation list, chat thread and contact panel, or each part on its own.

View as Markdown
Sample data
@polymorfa/react

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.

InboxRecipeExample.jsx
npm install @polymorfa/react@dev @polymorfa/browser@dev
import { 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.

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

ControlPermission
Conversation list and messagesread_messages
Live updatessubscribe_events
Composersend_message
Contact panelread_contact
Call button in the thread headervoip_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#

  • clientPolymorfaClient

    Defaults to the client from definePolymorfa().

  • sourceInboxDataSource

    Replaces the default route-backed source.

  • controllerInboxController

    Drives the inbox from outside.

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

    Appearance, text and extra CSS for this element.

EventdetailWhen
pmfa-selectThe conversationA conversation row is selected.
pmfa-renderThe 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.