@zitadel/components
v0.7.0
Published
Lit-based atomic web components and the <zitadel-login> orchestrator for the Zitadel auth UI.
Readme
@zitadel/components
Lit-based atomic web components and the <zitadel-login> orchestrator for the
Zitadel auth UI.
The package exports:
- Atoms —
<zl-field>,<zl-button>,<zl-alert>,<zl-icon>,<zl-pill>,<zl-card>,<zl-checkbox>,<zl-select>,<zl-page-shell>,<zl-sso-providers>, and<zl-passkey>(a WebAuthn ceremony handler that renders only its pending status and cancel button). Form-associated, accessible, branding-aware Lit elements that map 1:1 to the flow API field/action/error primitives and the Figma design system. - Orchestrators —
<zitadel-login>, a single drop-in element that calls the flow API, renders each step through a Liquid template, manages focus and form submission, and applies branding/theme/locale;<zitadel-logout>for sign-out; and<zitadel-session>, the post-sign-in "signed in" card (session read + sign-out in one element). - Tokens & manifests — design tokens (
--zl-*CSS custom properties), a Liquid template registry, and per-atom manifests describing allowed attributes/parts/events for sanitiser allowlists.
It is consumed directly by tenants embedding the auth UI on their own pages
and indirectly by the apps/console shell.
Status
Pre-release substrate. APIs are stabilising alongside
docs/design/branding/ and
docs/design/flowengine/. Expect minor breaks
until the first published version. See
docs/design/branding/form-participation.md
for the form-association / accessibility decisions baked into every input atom.
Install
corepack pnpm add @zitadel/components@latestlit, liquidjs, dompurify, and lucide are runtime dependencies and are intentionally
externalised so npm consumers dedupe with their own copies.
Quickstart — drop on a page
The 90% case: configure the SDK once, render the element, optionally set a
language. <zitadel-login> reads the global project handle from
configureZitadel() via getZitadelConfig() — no per-element wiring needed.
<script type="module">
import '@zitadel/components';
import { configureZitadel } from '@zitadel/api/config';
// Write-once: sets the global project handle (and the proxy path the
// generated client uses). The element picks this up automatically.
configureZitadel({ projectId: 'proj_123', proxyPath: '/__nextgen' });
const el = document.getElementById('login');
el.lang = 'en'; // optional; defaults to <html lang> / navigator.language
</script>
<!-- variant="page" = a dedicated login route that owns the viewport.
Omit it to embed a content-sized widget inside your own layout. -->
<zitadel-login id="login" variant="page" purpose="login"></zitadel-login>What <zitadel-login> handles for you:
POST /flowson mount,POST /flows/{flow_id}/submitfor every step, terminalredirect/showhonoured automatically.- Native
<form>semantics: Enter submits, password managers see the inputs,<button type="submit">works, browser autofill works. - Focus moved to the first field on every step change (and on load in
variant="page"; an embedded widget deliberately leaves initial focus alone so it can't scroll-jump the page it sits on). - Branding tokens mapped to CSS variables on the shadow root.
- Light and dark theme, hot-swappable: the
themeproperty, else the tenant'sbranding.theme.mode, else the variant default (pagedark,widgetfollowsprefers-color-scheme). - Mandatory gates (terms, captcha) enforced before submit.
- Output sanitised with DOMPurify against a per-atom allowlist before injection.
- Stateless server: the
_zflowHttpOnly cookie is the source of truth between requests; every call runs withcredentials: "include".
React / Astro / Next
Same element, lifted into JSX. Pass objects through ref rather than as
attributes (web component properties are typed objects, not stringified
attributes). Either configure the SDK globally with configureZitadel() and
let the element read it, or assign the returned handle to el.project.
import '@zitadel/components';
import { configureZitadel } from '@zitadel/api/config';
const project = configureZitadel({
projectId: 'proj_123',
proxyPath: import.meta.env.VITE_ZITADEL_PROXY_PATH,
});
export function Login({ locales }: Props) {
return (
<zitadel-login
purpose="login"
ref={(el) => {
if (!el) return;
el.project = project;
el.locales = locales;
}}
/>
);
}Mocking for offline demos and tests
The orchestrator calls the typed @zitadel/api fetch client
directly — there is no transport abstraction to swap. Intercept at the
network layer via the workspace-internal @zitadel/api-mock
package, which walks an xstate flow machine through identifier →
password → done (with register and SSO branches) using orval-typed step
fixtures:
- Tests (
msw/node) — passsetupMockHandlers()from@zitadel/api-mockintosetupServer(...).getCapturedRequests()exposes captured request bodies for assertions. - Browser (
msw/browser) —setupMock(worker)wires the handlers into amsw/browserworker. The Storybook orchestrator stories take the equivalent path throughmsw-storybook-addon(seeapps/storybook/src/orchestrator.stories.ts).applyBranding(...)injects a tenant branding overlay merged into every response (presets includefont_urlfor Inter). - Framework demos (TCP server) —
turbo run start --filter=@zitadel/api-mockserves the same handlers on port 8080 (PORToverrides it when the script runs through pnpm) withdefaultDevBranding(dark theme, no font) applied at boot. Seeapps/demo-nextandapps/demo-nuxt.
Preview surfaces
| Surface | Command | What it gives you |
| --- | --- | --- |
| Storybook | turbo run dev --filter=@zitadel/storybook (:6006) | The workbench for the Lit atoms and the <zitadel-login> orchestrator (MSW via msw-storybook-addon, flow/branding as controls). |
| demo-next | turbo run start --filter=@zitadel/api-mock + turbo run dev --filter=@zitadel/demo-next | Next.js SDK, middleware, cookies, built dist/ (:3002/login). See apps/demo-next. |
| demo-nuxt | mock on :8080, then turbo run dev --filter=@zitadel/demo-nuxt | Nuxt SDK, middleware, cookies, built dist/ (:3001/login). See apps/demo-nuxt. |
The Storybook dev server resolves @zitadel/components from source, so atom
edits hot-reload without a rebuild.
Atoms-only (bypass the orchestrator)
If you want a fully bespoke shell, use the atoms directly. You give up the template, transitions, and focus management; you keep the styled, accessible, form-associated inputs.
<form id="login">
<zl-field name="email" label="Email" type="email" autocomplete="username" required></zl-field>
<zl-button hierarchy="primary" type="submit" action="submit" label="Continue" block></zl-button>
</form>Customisation tiers
| Tier | Surface | Use when |
| --- | --- | --- |
| SDK config | configureZitadel({ projectId, proxyPath }) from @zitadel/api/config | every consumer — sets the project + proxy path the element reads |
| Tokens (server) | branding payload returned from the server | tenant colour / logo / font, managed centrally |
| Tokens (host page) | zitadel-login { --zl-…: … } in your own stylesheet | matching the widget to the app you embedded it in |
| Layout / placement | host CSS on zitadel-login { ... }, variant, --zl-page-min-height | sizing and positioning inside your layout |
| CSS hooks | zitadel-login::part(form), zitadel-login::part(field-input) | targeted overrides of atom internals |
| Locale | el.lang = 'de' / el.locales = { ... } | i18n / custom copy |
| MSW mocks | setupWorker / setupServer from msw | offline / staging / fixtures |
| Custom template | zitadel branding eject → edit Liquid → zitadel deploy, or branding.liquid_template on the payload | tenant-supplied layouts |
| Atoms-only | hand-built form | non-standard flow shells |
For styling, start with the generated --zl-* variables from
@zitadel/design-tokens, then use host CSS on zitadel-login { ... } for page
placement and ::part(...) hooks for targeted internals such as the form or
field input. The design-token package README is the canonical token catalogue;
the branding design notes explain the broader override ladder.
Your stylesheet is the strongest styling authority. A plain rule in the embedding app wins:
zitadel-login {
--zl-foreground: #101828;
--zl-card: #ffffff;
--zl-radius-md: 0.25rem;
}Those values reach the atoms' own shadow roots — custom properties inherit
across shadow boundaries — and they outrank both the design-system defaults
and the tenant's server-side branding, because the CSS cascade gives normal
declarations from the outer tree precedence over the :host rules the
orchestrator adopts internally. That ordering is deliberate: an app embedding
its own login should be able to match its design system without a server
round-trip. Leave the tokens alone and centrally-managed tenant branding
applies as before. customization.browser.spec.ts pins this.
Sizing is a two-mode contract. The default is variant="widget":
content-sized, transparent through every layer, no fonts injected into your
document, no focus grab on load — drop it into a section, sidebar, or modal
and your app keeps owning the page. Dedicated login routes opt into the
full-page chrome:
<zitadel-login variant="page"></zitadel-login>
<!-- claims the viewport, paints the surface background from tokens,
links the tenant's branding font_url if it has one,
focuses the first field -->Width-responsive chrome (the split designs' two-column collapse, the compact
brand header) keys off the widget's own width via container queries, so a
narrow embed on a desktop viewport lays out like a phone. Fine-grained height
control in either mode: --zl-page-min-height (inherits across the shadow
boundaries, releasing the orchestrator mount and the zl-page-shell atom in
one setting). embedding.browser.spec.ts pins this whole contract.
Fonts are opt-in. The package fetches no typeface of its own: the token
stacks name Arimo first and fall back to the system font, so an unbranded
login sends no request to a font CDN. To render a face, load it in your app
(next/font, @fontsource/*, your own @font-face), or set branding
typography.font_url, which a page links into the document <head>.
Colour mode ships light and dark. A page renders dark (the design
system's primary surface); a widget follows the visitor's
prefers-color-scheme so it doesn't force a dark card onto a light page.
Pin it when your app's surface is fixed:
<zitadel-login theme="light"></zitadel-login>Resolution runs strongest-first: this theme property → the tenant's
branding.theme.mode → the variant default. The resolved mode lands on
data-theme on the element, and every --zl-* token repaints with it.
Atom internals forward through the orchestrator as <atom>-<part> names —
zitadel-login::part(field-input), zitadel-login::part(button-root) — for
every part an atom's manifest declares; bare names (zl-field::part(input))
apply when composing atoms directly without the orchestrator
(exportparts.browser.spec.ts pins the forwarding).
Automation can use the stable host and native shadow-root hooks that the default
template emits. Host atoms expose hooks such as zitadel-field-email,
zitadel-field-password, and zitadel-action-submit; their native shadow
controls expose hooks such as zitadel-input-email, zitadel-input-password,
and zitadel-action-submit-button. Hooks are method-named even when the flow
engine names a credential field x-auth-methods#<method> — the name
attribute keeps that raw form key, only the data-testid hooks are normalised
(hookName in src/internal/hook-name.ts). For sign-out, <zitadel-session>'s
button carries zitadel-session-logout, and its native button
zitadel-session-logout-button. <zitadel-logout> has no hook. By default it
shows an avatar menu: open it ("Open user menu"), then target the .signout-btn
button in its shadow root. Given a <template> child, it shows that markup
instead, and the element marked data-action="logout" signs out.
A tenant Liquid template can already be supplied through the branding
payload's liquid_template field; a dedicated declarative template
surface on <zitadel-login> is not yet exposed. The orchestrator otherwise
renders the bundled default.liquid. Tracked as a follow-up.
Server rendering and late configuration
A server-rendered page ships the widget as a bare custom element, and the browser upgrades it as soon as the components bundle has run, usually before the framework has hydrated and handed the element its configuration. Attributes the server writes into the markup (project-id, proxy-path, purpose, flow-name) are there at upgrade, but properties (the project handle from configureZitadel(), locales) only arrive on hydration, and some wrappers set even the attribute-shaped values as properties once the element is running. <zitadel-login> reads its configuration once, when it starts, and does not restart when the configuration changes later: an element that starts with no resolvable project sends no request and shows "requires a configured project", and a purpose or flow-name that arrives after the start does not change the flow already running. <zitadel-session> and <zitadel-logout> wait for a project and fetch the identity once, with whatever resolved first.
So the configuration has to be there when the element starts. Give a raw element project-id and proxy-path as attributes in the server markup, configure globally with configureZitadel() before the bundle loads, or mount the widget on the client only, after hydration. Which of these a framework wrapper supports differs, so follow the page for your SDK.
Do not build on server-rendered markup that carries an object-valued prop. React 19 does not apply a custom element's object property while hydrating it, so a project handle passed to a raw <zitadel-login> that was server-rendered is never delivered. Pass project-id and proxy-path as strings, configure globally before the bundle loads, or mount on the client only.
Edge runtimes
Cloudflare Workers and Vercel Edge have no DOM, and bundlers target them with the browser condition next to workerd, worker or edge-light, so Lit's browser build throws HTMLElement is not defined as soon as it is imported. When one of those conditions is active together with browser, the package root therefore resolves to a build that never loads Lit and defines no element. It keeps what does not need one: businessLocales and the other locales, tokens and cssVars, the branding helpers, the attribution markup and the flow API client. The elements, their manifests, the sanitiser and ThemeController are not in it, so a bundle for those runtimes fails at build time if it imports one. The other entries (./atoms, ./manifests, ./orchestrator, ./standalone) are unchanged and still need a DOM, as does the root under browser alone. Without browser, workerd, worker and edge-light resolve to the full root as before.
Element APIs
<zitadel-login>
| Property | Type | Notes |
| --- | --- | --- |
| variant | 'widget' \| 'page' | Sizing/chrome mode. widget (default): content-sized, transparent, no font injection, no initial focus grab. page: full-page chrome for dedicated login routes |
| theme | 'light' \| 'dark' \| 'auto' | Colour mode. Unset defers to branding.theme.mode, then to the variant default (dark for page, auto for widget). Resolved value lands on data-theme |
| purpose | 'login' \| 'register' \| 'reset_password' \| string | Which flow purpose to drive |
| flowName / flow-name | string | Run the flow definition with this name instead of the project default |
| project | ZitadelProject | SDK handle from configureZitadel(). Object property (not an attribute). When unset, the element falls back to the global handle from getZitadelConfig() |
| lang | string | BCP 47 tag (e.g. "de", "en-US"). Resolves to a built-in dictionary; falls back to <html lang> / navigator.language |
| locales | Record<string, Locale> | Custom locale dictionaries keyed by language code; spread over the built-in dictionary so partial overrides work. The en entries also fill whatever another language has no text for |
| postSignInUrl / post-sign-in-url | string | After complete: "show", exchange the handoff_token for a session cookie and navigate here, or back to the path in the page's next query parameter when that is a path on the page's origin: every server SDK's middleware sends a signed-out visit to a protected route to the login page with ?next=<path>. A next that is a URL, starts with //, or holds a \ or a control character is ignored |
| forcePostSignInUrl / force-post-sign-in-url | boolean | Navigate to post-sign-in-url even when the page's next query parameter names a path, for a page that uses next for something of its own |
| resumeFlowId / resume-flow-id | string | Resume an existing flow handle instead of starting fresh. Unset, null or "" fall back to the flow query parameter. Every SDK's login wrapper takes it as resumeFlowId |
| previewState / preview-state | 'default' \| 'validation_error' \| 'submission_error' \| 'loading' \| 'success' | Preview mode for operator surfaces such as the console's branding screen. The flow still starts, so the step is the one the project serves; the element then shows it in this state and submits nothing. Only the purpose's entry step can be previewed. LOGIN_PREVIEW_STATES lists the values, and loginPreviewStatesFor(step) the ones that show a served step differently from default; any other value runs the flow for real |
| previewSuccessStep / preview-success-step | string | The terminal step the success preview paints, for a flow definition that names it differently from the default flow's done |
Events: zitadel-flow-input, zitadel-flow-step, zitadel-flow-complete,
zitadel-flow-error, zitadel-flow-redirect. zitadel-flow-step fires for
every applied step including the first, so a host app can drive its own chrome
(progress, headings, analytics) from mount onwards rather than from the first
submit. A heading follows step.purpose, login or register: the login
switches between them by itself when an email does or does not have an account,
and then shows the visitor a notice saying why. To hide the notice, set its text
to "" in locales (notice.user_not_found, notice.user_already_exists,
notice.sso_user_not_found). An "" under en hides it in every language,
unless that language has its own text for it.
zitadel-flow-redirect fires when a step hands the browser to an identity
provider, carrying the URL to send it to. The widget then navigates there
itself, with window.location.assign: the provider's authorization endpoint
is a full-page destination on another origin, so there is nothing a router
could do with it. The event is a notification, not a hook — it is not
cancelable, and a host listener cannot substitute its own navigation. Use it
to record the hand-off (analytics, a spinner, saving scroll state) before the
page goes away. The detail carries waitUntil(promise): the widget waits for
the promises its listeners pass, up to two seconds, before it navigates.
zitadel-flow-complete and zitadel-signout carry it too, for the navigation
that follows them. The framework wrappers surface it as onFlowRedirect, except
Vue and Angular, which emit flowRedirect, and Qwik, which takes
onFlowRedirect$.
The orchestrator exposes ::part(form) for tenant-side CSS hooks. Adopts
design tokens and branding.font_url into its shadow root on each update.
<zitadel-logout>
Session menu / sign-out control for embedded apps. Reads the signed-in
identity from getMySession (GET /sessions/me) — the same source as
<zitadel-session> — calls revokeMySession (DELETE /sessions/me) through
the SDK handle, and clears the session. The read and the revoke name the
handle's project: a session of another project on the same host, such as the
Console's on localhost, shows no identity and stays signed in. A session that
already ended, in another tab or by expiring, signs out without an error. Uses
the same token adoption as <zitadel-login> (applyBaseTokens).
| Property | Type | Notes |
| --- | --- | --- |
| project | ZitadelProject | SDK handle from configureZitadel(). Object property; falls back to the global handle from getZitadelConfig() |
| postSignOutUrl / post-sign-out-url | string | Navigate here after sign-out |
Supports a light-DOM <template> slot for a fully custom menu; default UI is
the avatar trigger + dropdown.
<zl-field>
Form-associated input. Participates in the parent <form>, supports validity
state, restores on form reset, and forwards Enter to form.requestSubmit().
| Property | Type | Notes |
| --- | --- | --- |
| name | string | Form key |
| label | string | Visible label (rendered above) |
| aria-label | string | Accessible name for the input when there is no label |
| type | 'text' \| 'email' \| 'password' \| ... | Native input type |
| value | string | Two-way bound; emits zl-input |
| placeholder, autocomplete, pattern | string | Forwarded |
| required, disabled, invalid | boolean | |
| error | string | Custom validity message |
Parts: root, label-row, label, forgot-link, input-wrap, input, trailing-icon, trailing-action, help, success, error.
<zl-button>
Single button atom covering every button variant:
| Attribute | Values | Notes |
| --- | --- | --- |
| hierarchy | primary \| secondary \| outline \| text | Visual rank |
| size | medium \| small | Surface size |
| type | submit \| button | When submit, takes part in the host <form> |
| action | string | Forwarded with the zl-submit CustomEvent |
| loading, disabled, block | boolean | |
| label | string | Convenience text; default slot is also supported |
Emits zl-submit for both primary submits and secondary navigations — the
orchestrator switches on type/action to decide whether to advance the flow
or just notify.
<zl-alert>
Inline status message for the four Figma severities (error \| success \|
warning \| info). Renders the matching icon automatically; supports an
optional heading and default-slot body.
<zl-sso-providers>
One outline button per identity provider the step offers. A provider's logo
shows automatically when <zl-icon> ships a brand-<template> mark for its
catalog template (SHIPPED_BRAND_ICON_NAMES); any other provider, including
a tenant's own OIDC connection, stays text-only rather than getting a stand-in
logo.
- Multicolour marks (Google) keep the vendor's colours.
- Monochrome marks (GitHub) carry no fill and follow the button's foreground, so they flip with light and dark mode.
- Every mark sits in the button's leading slot at 16px.
To add a provider's logo, add its official artwork to BRAND_GLYPHS in
src/atoms/zl-icon.ts and its name to BrandIconName and
SHIPPED_BRAND_ICON_NAMES; the buttons and the Storybook mock pick it up.
<zl-icon> / <zl-pill> / <zl-card> / <zl-page-shell>
Pure presentational atoms — icons render from a curated inline-SVG sprite,
pills carry the "Secured with Zitadel" attribution chip (and any tenant
alternative), and <zl-card> + <zl-page-shell> build the auth-screen
chrome from design tokens.
See src/atoms/ for full TypeScript types and JSDoc.
Project layout
packages/components/
├── src/
│ ├── atoms/ zl-field, zl-button, zl-alert, zl-icon, zl-pill,
│ │ zl-card, zl-checkbox, zl-select, zl-page-shell,
│ │ zl-sso-providers, zl-passkey + tests
│ ├── orchestrator/ <zitadel-login>, <zitadel-logout>, <zitadel-session>,
│ │ api-client, liquid, branding
│ │ ├── locales/ bundled locales (en, de, it) + business copy
│ │ └── templates/ default.liquid (all steps) + layout-chrome.css
│ ├── tokens/ re-export of @zitadel/design-tokens
│ ├── styles/ shared host styles, focus ring, t() css-var bridge
│ ├── manifests.ts per-atom attribute / part / event manifests
│ ├── server.ts Lit-free subset the root resolves to on edge
│ └── index.ts barrel
├── tsdown.config.ts library build (externalises lit/liquidjs/dompurify)
└── vitest.config.ts jsdom (unit) + chromium (browser) projectsThe interactive workbench (the atoms and the <zitadel-login>
orchestrator) lives in apps/storybook.
Develop
Use Turborepo for tasks in this monorepo
(turbo run <task> --filter=<package>). It matches CI caching and dependency
order. Direct pnpm --filter ... scripts still exist on some packages for
leaf-package debugging, but turbo is the documented path.
# install once at the repo root
corepack pnpm install
# --- Workbench ---
# Storybook: the atoms and the <zitadel-login> orchestrator
turbo run dev --filter=@zitadel/storybook
# → http://localhost:6006
# Framework demos (TCP mock + SDK) — see apps/demo-*/README.md
# turbo run start --filter=@zitadel/api-mock # → http://localhost:8080
# turbo run dev --filter=@zitadel/demo-next # → :3002 (ZITADEL_URL defaults to :8080)
# turbo run dev --filter=@zitadel/demo-nuxt # → :3001 (ZITADEL_URL defaults to :8080)
# --- Package checks ---
turbo run test --filter=@zitadel/components # unit + browser projects
turbo run typecheck --filter=@zitadel/components
turbo run build --filter=@zitadel/componentsThe Storybook dev server loads this package from source; the storybook's
build and test depend on @zitadel/components#build.
Framework demos need the TCP mock plus a rebuild after orchestrator changes —
see apps/demo-next/README.md and
apps/demo-nuxt/README.md.
Testing strategy
Tests are split across two Vitest projects:
unit—jsdom, fast feedback for rendering, Liquid wiring, branding validation, sanitiser allowlists, and DOM-level a11y attributes.browser— real Chromium via Playwright, covers behaviourjsdomcan't fake:ElementInternals/ form-associated state, native form submit interception, focus delegation across shadow roots.
Files ending in .browser.spec.ts run only in the browser project; everything
else runs in jsdom.
Related design docs
docs/design/branding/— token spec, theme, template chrome, and the form-participation ADR.docs/design/flowengine/— flow engine, step shape, template security, visualizer.
License
MIT — see LICENSE.
