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

Appearance and styling

Theme the UI Kit with variables, dark colors, slot classes, CSS parts, your own stylesheet and locale text.

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.

UI Kit components use one shared stylesheet. You can change it at five levels, from lightest to fullest control: variables, dark colors, slot classes and styles, your own CSS, and unstyled mode.

Pass an appearance object to PolymorfaProvider, to definePolymorfa(), or to an element's configuration property:

TSX
<PolymorfaProvider
  tokenEndpoint="/api/polymorfa/token"
  appearance={{
    theme: "system",
    variables: { colorPrimary: "#0f766e", radiusMedium: "8px" },
    darkVariables: { colorPrimary: "#14b8a6" },
    elements: { bubble: { styles: { borderRadius: "6px" } } },
  }}
>
  <Inbox />
</PolymorfaProvider>

Appearance fields#

FieldTypeDefaultDescription
theme"light" | "dark" | "system""system"system follows the operating system's color scheme.
variablesPartial<AppearanceVariables>See belowColors, type, spacing, radii, shadow and motion.
darkVariablesPartial<AppearanceVariables>Built-in dark paletteDark theme colors. Only color keys apply.
layoutPartial<AppearanceLayout>See belowText direction and drawer width.
elementsRecord<slot, { className?, styles?, surface? }>{}Class names and inline styles for one slot.
unstyledbooleanfalseSkip the bundled stylesheet. Components keep their classes, slots and parts.

Variables#

Each variable becomes a CSS custom property on the component root.

VariableCSS propertyDefault
colorPrimary--pmfa-color-primary#5b4bf7
colorBackground--pmfa-color-background#ffffff
colorForeground--pmfa-color-foreground#17151f
colorMuted--pmfa-color-muted#6d6878
colorBorder--pmfa-color-border#dedbe5
colorDanger--pmfa-color-danger#c62828
colorSuccess--pmfa-color-success#18794e
fontFamily--pmfa-font-familyInter, ui-sans-serif, system-ui, sans-serif
fontSizeBase--pmfa-font-size-base16px
spacingSmall--pmfa-spacing-small8px
spacingMedium--pmfa-spacing-medium12px
spacingLarge--pmfa-spacing-large20px
radiusSmall--pmfa-radius-small6px
radiusMedium--pmfa-radius-medium10px
radiusLarge--pmfa-radius-large16px
shadowPanel--pmfa-shadow-panel0 18px 50px rgb(23 21 31 / 0.16)
motion--pmfa-motionsystem (full, reduced or system)

Layout#

FieldDefaultDescription
direction"auto"ltr or rtl. auto uses the locale's direction.
drawerWidth400pxWidth of the chat drawer, set as --pmfa-drawer-width.

density, dialogWidth and callAspectRatio are accepted, but no component reads them in the current prerelease.

Dark colors#

theme: "dark" uses the dark palette. theme: "system" uses it when the system prefers dark. darkVariables overrides dark colors one at a time and is emitted as --pmfa-dark-color-*, for example --pmfa-dark-color-primary. Unset dark colors use the built-in dark palette, except colorPrimary, which falls back to your light primary.

Chat variables#

Chat surfaces derive their colors from the variables above. Set these custom properties on any ancestor to change one surface:

VariableDefault
--pmfa-chat-backgroundA light tint of the background and primary
--pmfa-chat-panelThe background color
--pmfa-chat-patternA faint dot grid. Set none to remove it.
--pmfa-bubble-incomingThe background color
--pmfa-bubble-outgoingThe primary color at 13% on the background
--pmfa-bubble-outgoing-textThe foreground color
--pmfa-bubble-radius8px
--pmfa-message-font-size0.9375em
--pmfa-receipt-readA blue for read and played receipts
--pmfa-unreadThe primary color, for unread badges

Each has a --pmfa-dark-* counterpart, such as --pmfa-dark-bubble-outgoing, except --pmfa-chat-pattern, --pmfa-bubble-radius, --pmfa-message-font-size and --pmfa-unread.

Call variables#

Call components read the shared variables: the accent follows colorForeground, Answer uses colorSuccess, Decline and Hang up use colorDanger, and cards use colorBackground, colorMuted, colorBorder, radiusMedium and fontFamily. The call stage is always dark. Call styles are scoped under the .pmfa-calls class.

Override with your own CSS #

Every bundled rule sits in the polymorfa cascade layer. Any unlayered CSS in your app overrides it, whatever its specificity:

CSS
.pmfa-bubble {
  border-radius: 6px;
}

Slots #

Every structural node has a slot name. Use it three ways:

  • appearance.elements[slot] adds a className and inline styles to the node. Style keys can be camelCase, kebab-case or custom properties.
  • React components take a classNames prop keyed by slot, and set data-slot on each node.
  • Web Components add the slot's part name to the node's part attribute, for ::part() selectors.
TSX
<MessageList
  controller={conversation}
  classNames={{ messageList: "my-log", dateSeparator: "my-date" }}
/>
CSS
pmfa-message-list::part(bubble) {
  border-radius: 6px;
}
pmfa-chat-drawer::part(drawer-header) {
  background: #0f766e;
  color: white;
}
SlotPartNode
chatWindowchat-windowInline chat window
chatHeaderchat-headerChat window header
chatFooterchat-footerChat window footer
messageListmessage-listScrolling message log
messagemessageOne message row
bubblebubbleMessage bubble
messageMetamessage-metaTime and delivery status
messageActionsmessage-actionsReply and Retry group
replyButtonreply-buttonReply action
retryButtonretry-buttonRetry action on a failed message
attachmentattachmentImage thumbnail or file card
replyQuotereply-quoteQuoted message above a reply
dateSeparatordate-separator"Today", "Yesterday" or a date
loadMoreload-moreLoad earlier messages button
latestButtonlatest-buttonJump to the latest message
emptyemptyEmpty conversation text
composercomposerComposer form
composerInputcomposer-inputMessage field
composerSendcomposer-sendSend button
composerAttachcomposer-attachAttach button
composerToolbarcomposer-toolbarComposer button and field row
emojiButtonemoji-buttonEmoji picker button
emojiPickeremoji-pickerEmoji picker popover
voiceButtonvoice-buttonRecord voice note button
recordingBarrecording-barVoice note recording bar
quickReplyMenuquick-reply-menuQuick reply list
attachmentChipattachment-chipPending attachment
replyBannerreply-banner"Replying to" banner
drawerdrawerDrawer panel
drawerHeaderdrawer-headerDrawer header
drawerTitledrawer-titleDrawer title
drawerClosedrawer-closeDrawer close button
templateBuildertemplate-builderTemplate editor panel
fieldfieldLabelled field or field group
labellabelField label
inputinputTemplate input or text area
actionsactionsTemplate action row
primaryButtonprimary-buttonSave draft
buttonbuttonPreview and Submit to Meta
previewpreview-panelTemplate preview area
errorerrorError message
inboxinboxInbox root
conversationListconversation-listConversation list
conversationSearchconversation-searchConversation search field
conversationItemconversation-itemOne conversation row
avataravatarContact avatar
unreadBadgeunread-badgeUnread count
threadthreadOpen conversation
threadHeaderthread-headerOpen conversation header
backButtonback-buttonBack to the list on narrow screens
contactPanelcontact-panelContact panel
connectButtonconnect-buttonConnect WhatsApp button
sessionStatussession-statusConnection status badge
callButtoncall-buttonCall button
templateManagertemplate-managerTemplate manager
templateListtemplate-listTemplate list
templateItemtemplate-itemOne template row

The preview slot uses the part name preview-panel, because the Preview button already uses preview. Web Components also keep earlier part names, such as meta, input, send, header, title and close.

Web Component stylesheets#

For rules that ::part() cannot express, such as descendants or states, set configuration.stylesheet. It takes CSS text, a CSSStyleSheet, or an array of either, and is applied inside the shadow root after the default stylesheet:

TypeScript
element.configuration = {
  appearance: { theme: "dark" },
  stylesheet: `.pmfa-msg-out .pmfa-bubble { border-end-end-radius: 18px; }`,
};

Unstyled mode#

unstyled: true skips the bundled stylesheet. Components still render their pmfa-* classes, data-slot attributes (React) and part names (Web Components), so you can style them from scratch. With Web Components, your configuration.stylesheet is the only stylesheet in the shadow root.

Locale and text #

All visible text comes from the locale. The default is English. Create a locale with createLocale(code, messages, direction) from @polymorfa/ui, overriding any message key; unset keys use English.

TSX
import { createLocale } from "@polymorfa/ui";

const locale = createLocale("en-GB", {
  "composer.placeholder": "Write a reply",
  "templates.empty": "No templates yet",
});

<PolymorfaProvider tokenEndpoint="/api/polymorfa/token" locale={locale}>
  <Inbox />
</PolymorfaProvider>;

ENGLISH_MESSAGES lists every key. The direction is rtl for Arabic, Persian, Hebrew, Pashto and Urdu codes and ltr otherwise; pass "ltr" or "rtl" as the third argument to set it. Message times and dates are formatted for the locale code.

Reduced motion#

All components stop animations and transitions when the user's system sets prefers-reduced-motion: reduce. The motion variable is emitted as --pmfa-motion for your own CSS; the bundled stylesheet follows the system setting.