npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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@latest

lit, 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 /flows on mount, POST /flows/{flow_id}/submit for every step, terminal redirect / show honoured 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 theme property, else the tenant's branding.theme.mode, else the variant default (page dark, widget follows prefers-color-scheme).
  • Mandatory gates (terms, captcha) enforced before submit.
  • Output sanitised with DOMPurify against a per-atom allowlist before injection.
  • Stateless server: the _zflow HttpOnly cookie is the source of truth between requests; every call runs with credentials: "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) — pass setupMockHandlers() from @zitadel/api-mock into setupServer(...). getCapturedRequests() exposes captured request bodies for assertions.
  • Browser (msw/browser) — setupMock(worker) wires the handlers into a msw/browser worker. The Storybook orchestrator stories take the equivalent path through msw-storybook-addon (see apps/storybook/src/orchestrator.stories.ts). applyBranding(...) injects a tenant branding overlay merged into every response (presets include font_url for Inter).
  • Framework demos (TCP server) — turbo run start --filter=@zitadel/api-mock serves the same handlers on port 8080 (PORT overrides it when the script runs through pnpm) with defaultDevBranding (dark theme, no font) applied at boot. See apps/demo-next and apps/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) projects

The 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/components

The 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 behaviour jsdom can'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

License

MIT — see LICENSE.