UI Kit
Prebuilt inbox, chat, calling, connection and template components for your web app, in React or as Web Components.
- PolymorfaProvider5 props
- ChatDrawer17 props
- ChatWindow13 props
- ComposeBox20 props
- MessageList8 props
- TemplateBuilder5 props
- CallControls5 props
- CallStage8 props
- CallSurface11 props
- DialPad6 props
- IncomingCallCard8 props
- ParticipantList4 props
- ParticipantVideoGrid4 props
- ConnectWhatsAppButton7 props
- ContactPanel7 props
- ConversationList12 props
- ConversationListView17 props
- Inbox11 props
- SessionStatus3 props
- TemplateManager3 props
- CallButton9 props
- CallNumberPicker5 props
The Polymorfa UI Kit is a set of prebuilt interface components for WhatsApp features in your own web app. Its components render an inbox, a chat thread and composer, call controls, a connect button and a template editor. Each component runs in the browser with a short-lived client token; your team key stays on your server.
Packages#
| Package | Install | Use it for |
|---|---|---|
@polymorfa/react | npm install @polymorfa/react@dev @polymorfa/browser@dev | React components and hooks. Requires React 18.2 or later (below 20). |
@polymorfa/elements | npm install @polymorfa/elements@dev @polymorfa/browser@dev | Web Components (<pmfa-inbox>, <pmfa-call> and others) for plain HTML, Vue, Svelte or any framework. |
@polymorfa/browser | Installed with either package above | Client tokens, controllers and the browser Calls client. Use it directly to build your own interface. |
@polymorfa/ui | Installed with either package above | Appearance, locale and styling helpers shared by both component packages. |
@polymorfa/nextjs | npm install @polymorfa/nextjs@dev @polymorfa/sdk@dev | Server route that mints client tokens and serves history, events, QuickLink and templates to the components. Works with Next.js, Express and Hono. |
The React and Web Component packages render the same markup, class names and stylesheet. The React package has more parts: the contact panel, participant video tiles, the call pop-out window, the call button and the template manager are React only.
Components#
Conversation list, chat thread and contact panel in one component.
ChatMessage list, composer, inline chat window and chat drawer.
CallsIncoming call card, call stage, controls, dial pad and call button.
Connect and statusConnect a WhatsApp number through QuickLink and show connection state.
TemplatesEdit, preview and submit message templates.
AppearanceThemes, variables, slots, CSS parts and locale text.
How the browser authenticates #
UI Kit components never receive your team key or project token. The flow is:
- The signed-in user's browser posts to a token route on your own origin. The default path is
/api/polymorfa/token. - Your server checks who the user is, decides what they may do, and mints a client token with API Mint client token.
- The components use that token for Polymorfa requests and fetch a new one 60 seconds before it expires.
Your token route also returns the grant it applied: the session (or Customer), the conversations the user may read and the allowed actions. Components hide controls the grant does not allow, such as the composer without send_message, and log one warning in development builds. Hiding is presentation only. Polymorfa and your route enforce every action again on each request.
See Installation and setup to add the route and the provider.
Choose a package#
- React app. Use
@polymorfa/react. Wrap your app inPolymorfaProviderand drop in<Inbox/>or individual parts. - Any other framework or plain HTML. Use
@polymorfa/elements. CalldefinePolymorfa()once, then place the custom elements in your markup. - Your own interface. Use the controllers in
@polymorfa/browserand read their snapshots. Both component packages render from the same controllers, so you can mix custom and prebuilt parts.
Related#
- Client tokens and the mint client token reference
- Calls guide
- QuickLink
- Install the TypeScript SDK