Appearance and styling
Theme the UI Kit with variables, dark colors, slot classes, CSS parts, your own stylesheet and locale text.
Customize
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:
<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#
| Field | Type | Default | Description |
|---|---|---|---|
theme | "light" | "dark" | "system" | "system" | system follows the operating system's color scheme. |
variables | Partial<AppearanceVariables> | See below | Colors, type, spacing, radii, shadow and motion. |
darkVariables | Partial<AppearanceVariables> | Built-in dark palette | Dark theme colors. Only color keys apply. |
layout | Partial<AppearanceLayout> | See below | Text direction and drawer width. |
elements | Record<slot, { className?, styles?, surface? }> | {} | Class names and inline styles for one slot. |
unstyled | boolean | false | Skip the bundled stylesheet. Components keep their classes, slots and parts. |
Variables#
Each variable becomes a CSS custom property on the component root.
| Variable | CSS property | Default |
|---|---|---|
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-family | Inter, ui-sans-serif, system-ui, sans-serif |
fontSizeBase | --pmfa-font-size-base | 16px |
spacingSmall | --pmfa-spacing-small | 8px |
spacingMedium | --pmfa-spacing-medium | 12px |
spacingLarge | --pmfa-spacing-large | 20px |
radiusSmall | --pmfa-radius-small | 6px |
radiusMedium | --pmfa-radius-medium | 10px |
radiusLarge | --pmfa-radius-large | 16px |
shadowPanel | --pmfa-shadow-panel | 0 18px 50px rgb(23 21 31 / 0.16) |
motion | --pmfa-motion | system (full, reduced or system) |
Layout#
| Field | Default | Description |
|---|---|---|
direction | "auto" | ltr or rtl. auto uses the locale's direction. |
drawerWidth | 400px | Width 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:
| Variable | Default |
|---|---|
--pmfa-chat-background | A light tint of the background and primary |
--pmfa-chat-panel | The background color |
--pmfa-chat-pattern | A faint dot grid. Set none to remove it. |
--pmfa-bubble-incoming | The background color |
--pmfa-bubble-outgoing | The primary color at 13% on the background |
--pmfa-bubble-outgoing-text | The foreground color |
--pmfa-bubble-radius | 8px |
--pmfa-message-font-size | 0.9375em |
--pmfa-receipt-read | A blue for read and played receipts |
--pmfa-unread | The 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:
.pmfa-bubble {
border-radius: 6px;
}Slots #
Every structural node has a slot name. Use it three ways:
appearance.elements[slot]adds aclassNameand inlinestylesto the node. Style keys can be camelCase, kebab-case or custom properties.- React components take a
classNamesprop keyed by slot, and setdata-sloton each node. - Web Components add the slot's part name to the node's
partattribute, for::part()selectors.
<MessageList
controller={conversation}
classNames={{ messageList: "my-log", dateSeparator: "my-date" }}
/>pmfa-message-list::part(bubble) {
border-radius: 6px;
}
pmfa-chat-drawer::part(drawer-header) {
background: #0f766e;
color: white;
}| Slot | Part | Node |
|---|---|---|
chatWindow | chat-window | Inline chat window |
chatHeader | chat-header | Chat window header |
chatFooter | chat-footer | Chat window footer |
messageList | message-list | Scrolling message log |
message | message | One message row |
bubble | bubble | Message bubble |
messageMeta | message-meta | Time and delivery status |
messageActions | message-actions | Reply and Retry group |
replyButton | reply-button | Reply action |
retryButton | retry-button | Retry action on a failed message |
attachment | attachment | Image thumbnail or file card |
replyQuote | reply-quote | Quoted message above a reply |
dateSeparator | date-separator | "Today", "Yesterday" or a date |
loadMore | load-more | Load earlier messages button |
latestButton | latest-button | Jump to the latest message |
empty | empty | Empty conversation text |
composer | composer | Composer form |
composerInput | composer-input | Message field |
composerSend | composer-send | Send button |
composerAttach | composer-attach | Attach button |
composerToolbar | composer-toolbar | Composer button and field row |
emojiButton | emoji-button | Emoji picker button |
emojiPicker | emoji-picker | Emoji picker popover |
voiceButton | voice-button | Record voice note button |
recordingBar | recording-bar | Voice note recording bar |
quickReplyMenu | quick-reply-menu | Quick reply list |
attachmentChip | attachment-chip | Pending attachment |
replyBanner | reply-banner | "Replying to" banner |
drawer | drawer | Drawer panel |
drawerHeader | drawer-header | Drawer header |
drawerTitle | drawer-title | Drawer title |
drawerClose | drawer-close | Drawer close button |
templateBuilder | template-builder | Template editor panel |
field | field | Labelled field or field group |
label | label | Field label |
input | input | Template input or text area |
actions | actions | Template action row |
primaryButton | primary-button | Save draft |
button | button | Preview and Submit to Meta |
preview | preview-panel | Template preview area |
error | error | Error message |
inbox | inbox | Inbox root |
conversationList | conversation-list | Conversation list |
conversationSearch | conversation-search | Conversation search field |
conversationItem | conversation-item | One conversation row |
avatar | avatar | Contact avatar |
unreadBadge | unread-badge | Unread count |
thread | thread | Open conversation |
threadHeader | thread-header | Open conversation header |
backButton | back-button | Back to the list on narrow screens |
contactPanel | contact-panel | Contact panel |
connectButton | connect-button | Connect WhatsApp button |
sessionStatus | session-status | Connection status badge |
callButton | call-button | Call button |
templateManager | template-manager | Template manager |
templateList | template-list | Template list |
templateItem | template-item | One 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:
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.
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.