# UI Kit

> Prebuilt inbox, chat, calling, connection and template components for your web app, in React or as Web Components.

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](https://docs.polymorfa.com/development/client-tokens); your team key stays on your
server.

> **Warning**
>
> Every UI Kit package is a development prerelease. Install from the npm `dev`
> tag and pin the exact version, for example `0.1.0-dev.20261017182310`. Names and
> props can change between prereleases.

## 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

- **[Inbox](https://docs.polymorfa.com/ui-kit/inbox)**
Conversation list, chat thread and contact panel in one component.

- **[Chat](https://docs.polymorfa.com/ui-kit/chat)**
Message list, composer, inline chat window and chat drawer.

- **[Calls](https://docs.polymorfa.com/ui-kit/calls)**
Incoming call card, call stage, controls, dial pad and call button.

- **[Connect and status](https://docs.polymorfa.com/ui-kit/connect)**
Connect a WhatsApp number through QuickLink and show connection state.

- **[Templates](https://docs.polymorfa.com/ui-kit/templates)**
Edit, preview and submit message templates.

- **[Appearance](https://docs.polymorfa.com/ui-kit/appearance)**
Themes, 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:

1. The signed-in user's browser posts to a token route on your own origin.
   The default path is `/api/polymorfa/token`.
2. Your server checks who the user is, decides what they may do, and mints a
   client token with `POST /platform/client-tokens`.
3. 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](https://docs.polymorfa.com/ui-kit/setup) to add the route and the provider.

## Choose a package

- **React app.** Use `@polymorfa/react`. Wrap your app in `PolymorfaProvider`
  and drop in `<Inbox/>` or individual parts.
- **Any other framework or plain HTML.** Use `@polymorfa/elements`. Call
  `definePolymorfa()` once, then place the custom elements in your markup.
- **Your own interface.** Use the controllers in `@polymorfa/browser` and read
  their snapshots. Both component packages render from the same controllers, so
  you can mix custom and prebuilt parts.

## Related

- [Client tokens](https://docs.polymorfa.com/development/client-tokens) and the
  [mint client token](https://docs.polymorfa.com/api/client-tokens/mint-client-token) reference
- [Calls guide](https://docs.polymorfa.com/calls)
- [QuickLink](https://docs.polymorfa.com/numbers/quicklink)
- [Install the TypeScript SDK](https://docs.polymorfa.com/get-started/development-environment#install-the-typescript-sdk)
