@zitadel/sdk-react
v0.7.0
Published
React components for the Zitadel auth UI (client-side SPA).
Readme
@zitadel/sdk-react
React components for the Zitadel auth UI, for client-side SPAs.
Installation
pnpm add @zitadel/sdk-react@latestRequirements
Peer dependencies: react >=18 and react-dom >=18.
TypeScript ≥ 5.0, the floor shared by every SDK; see the compatibility notes.
Usage
import {
ZitadelLogin,
ZitadelLogout,
configureZitadel,
} from '@zitadel/sdk-react';
// Configure once, before rendering. The handle is passed to the widget as a
// prop, so it has config the moment it mounts.
const project = configureZitadel({
projectId: '<your project id>', // e.g. from your bundler's env (import.meta.env, process.env, …)
proxyPath: '/__nextgen', // same-origin path your deploy proxies to the backend
});
export function LoginPage() {
return <ZitadelLogin project={project} purpose="login" postSignInUrl="/" />;
}
export function ProfilePage() {
return <ZitadelLogout project={project} postSignOutUrl="/login" />;
}ZitadelLogin also takes resumeFlowId, an existing flow to resume instead of starting a new one; unset, null or "" falls back to the flow query parameter.
The signed-in session card is <ZitadelSession project={project} /> (exported
as ZitadelSession).
Widget props and events
ZitadelLogin, ZitadelLogout and ZitadelSession take the props below, spelled the same in every SPA SDK. An unset prop keeps the widget's own default.
| Prop | Type | Default | Widgets | Description |
| --- | --- | --- | --- | --- |
| project | ZitadelProject | unset | Login, Logout, Session | The handle from configureZitadel(...). Wins over projectId and proxyPath. |
| projectId | string | unset | Login, Logout, Session | Project id, read when no project handle is passed. |
| proxyPath | string | "/__nextgen" | Login, Logout, Session | Same-origin path the widget calls. |
| purpose | CreateFlowBodyPurpose | "login" | Login | Flow purpose. |
| flowName | string | unset | Login | Runs the flow definition with this name; unset runs the project's default flow for the purpose. |
| postSignInUrl | string | unset | Login | Where to navigate after a completed sign-in. When the page's next query parameter names a path on the same origin, as the server SDKs' middleware sets it for a signed-out visit to a protected route, the widget returns there instead. |
| forcePostSignInUrl | boolean | false | Login | Navigates to postSignInUrl even when the page's next query parameter names a path, for a page that uses next for something of its own. |
| postSignOutUrl | string | unset | Logout, Session | Where to navigate after sign-out. |
| resumeFlowId | string or null | unset | Login | An existing flow's id to resume instead of starting a new flow; unset, null or "" falls back to the flow query parameter, and an id that no longer resolves starts a new flow. |
| variant | "widget" or "page" | "widget" | Login, Session | widget is content-sized and paints no page chrome; page claims the viewport, paints the surface background and loads the brand font, and on Login focuses the first field. |
| theme | "light", "dark" or "auto" | unset | Login, Logout, Session | Colour mode. Unset follows the tenant's branding theme on Login, then the variant default (dark for page, auto for widget); Logout defaults to auto. auto follows prefers-color-scheme. |
| suppressHeader | boolean | false | Login, Session | Visually hides the widget's own heading block while keeping it in the accessibility tree, for pages that already carry the heading. |
| suppressPasswordToggle | boolean | false | Login | Hides the show/hide button on password fields. |
| heading | string | "Signed in as" | Session | Heading text override. |
| logoutLabel | string | "Sign out" | Session | Logout action label override. |
| locales | Record<string, Partial<Record<string, string>>> | unset | Login | Copy overrides merged over the builtin dictionaries, keyed by primary language subtag, for example { en: { "identifier.title": "Welcome back" } }. |
| lang | string | browser language | Login | BCP-47 language override. |
Each widget event reaches the callback in the last column, which receives the event's detail payload.
| Widget event | Fires when | Detail | Widgets | Callback |
| --- | --- | --- | --- | --- |
| zitadel-flow-step | Login shows a step, the first one included. | { step } | Login | onFlowStep |
| zitadel-flow-input | The visitor edits a field. | { name, value } | Login | onFlowInput |
| zitadel-flow-complete | The flow reaches a terminal step. | { behavior, redirect_uri?, handoff_token?, handoff_token_expires_at? } | Login | onFlowComplete |
| zitadel-flow-redirect | The widget hands the browser to an identity provider; nobody is signed in yet. | { redirect_url, step } | Login | onFlowRedirect |
| zitadel-flow-error | The flow reports an error. | { message } | Login | onFlowError |
| zitadel-signout | The user signs out. | { display, identifier } | Logout, Session | onSignout |
<ZitadelLogin project={project} theme="light" onFlowComplete={(detail) => track(detail)} />When your callback for zitadel-flow-complete, zitadel-flow-redirect or zitadel-signout returns a promise, the widget waits for it to settle (up to two seconds) before it navigates.
Standard HTML attributes
ZitadelLogin, ZitadelLogout and ZitadelSession also take the standard HTML attributes (className, style, id, title, slot, hidden, role, tabIndex, data-* and aria-*) and pass them to the widget element, so you can position, style and label the widget without an extra wrapper element. Nothing else reaches the element: any other prop is ignored.
<ZitadelLogin project={project} className="login" data-testid="login" aria-label="Sign in" />Server rendering
If your app renders on the server, mount the widget on the client only, after hydration, or pass project-id and proxy-path to the ZitadelLogin wrapper as strings (they are written into the server markup as attributes), because a widget that starts before its configuration arrives shows an error instead of the flow.
React 19 does not apply an object property such as project while hydrating a server-rendered custom element, so on a server-rendered page pass project-id and proxy-path as strings instead of a project handle.
Edge runtimes
The wrapper loads on edge runtimes such as Cloudflare Workers and Vercel Edge, which have no DOM. It renders each widget by its tag name there and registers the elements only in the browser, so the markup a server sends is the same on every runtime.
The edge checks run against React 19. A server render of a widget with React 18.3 under the browser condition, which is how bundlers resolve @lit/react for the edge, logs React's development-only warning that useLayoutEffect does nothing on the server (twice per widget) and renders the same markup; the Node build of @lit/react logs nothing, and the production build of React drops the warning.
Proxying to the backend (deployment)
The widgets call ${proxyPath}/… same-origin (default /__nextgen). In
production the same-origin path must come from your hosting platform — until
the CLI can scaffold those configs, production SPA deployment is not yet
supported; see
ADR 036
and zitadel/nextgen#560. The
CLI dev proxy covers local development.
For local development you can also skip the proxy and point proxyPath
straight at the backend (cross-origin), e.g. proxyPath: "http://localhost:8080"
(the zitadel start local runtime default port).
Testing
To test an app that uses this SDK end to end, against a real local Zitadel server, use @zitadel/testing (guide).
