@zitadel/sdk-vue

@zitadel/sdk-vue

Vue 3 components for the Zitadel auth UI, for client-side SPAs (Vite, etc.).

Installation

pnpm add @zitadel/sdk-vue@latest

Requirements

Peer dependencies: vue >=3.2.

TypeScript ≥ 5.0, the floor shared by every SDK; see the compatibility notes.

Usage

<script setup lang="ts">
import { ZitadelLogin, configureZitadel } from '@zitadel/sdk-vue';

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

<template>
  <ZitadelLogin :project="project" purpose="login" postSignInUrl="/" />
</template>

<ZitadelLogout :project="project" postSignOutUrl="/login" /> works the same way.

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.

Each widget event reaches the callback in the last column, which receives the event's detail payload.

<ZitadelLogin :project="project" theme="light" @flowComplete="track" />

The zitadel-flow-complete, zitadel-flow-redirect and zitadel-signout details carry a waitUntil(promise); call it from your handler to make the widget wait for your async work before it navigates.

Standard HTML attributes

ZitadelLogin, ZitadelLogout and ZitadelSession also take the standard HTML attributes (class, 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" class="login" data-testid="login" aria-label="Sign in" />

Vue's strictTemplates rejects data-* attributes on a component whose props type does not declare them, and this one cannot declare them without breaking Vue's own overloads.

Server rendering

If your app renders on the server, mount the widget on the client only, after hydration (the ZitadelLogin wrapper sets projectId and proxyPath as element properties, so adding them to the wrapper does not put them in server markup), or use a raw <zitadel-login> element with project-id and proxy-path as attributes, because a widget that starts before its configuration arrives shows an error instead of the flow.

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).