React SDK

The React SDK is the SPA wrapper for the shared Zitadel login and logout widgets.

SPA proxy requirement

React apps do not have server middleware by default. The CLI configures a Vite dev proxy; production deployments need an equivalent same-origin proxy for /__nextgen/*. See SDK proxy.

Install

pnpm add @zitadel/sdk-react

npm install @zitadel/sdk-react

yarn add @zitadel/sdk-react

Setup

The CLI configures the Vite proxy, writes app-level auth UI, adds environment files, and installs the SDK.

src/App.tsx

vite.config.ts

.env.local

.env.example

package.json

Configure Zitadel once, then render login and logout widgets:

import { ZitadelLogin, ZitadelLogout, configureZitadel } from "@zitadel/sdk-react";

const project = configureZitadel({
  projectId: import.meta.env.VITE_ZITADEL_PROJECT_ID,
  proxyPath: "/__nextgen",
});

export function LoginPage() {
  return <ZitadelLogin project={project} purpose="login" postSignInUrl="/" />;
}

export function ProfilePage() {
  return <ZitadelLogout project={project} postSignOutUrl="/login" />;
}

Runtime model

The widgets call the configured proxy path on the same origin.

In local Vite development, the generated proxy forwards /__nextgen/* to Zitadel and attaches the project service key.

In production, deploy an equivalent edge/backend proxy or intentionally configure a backend URL for local-only experiments.

Verify

Run the Vite app with generated environment variables.
Register or sign in through the rendered widget.
Confirm logout returns to the configured login path.
In browser automation, use shadow-DOM-aware locators because the native inputs live inside shared web components.

React SDK

Install

Setup

Runtime model

Verify

See also

On this page