# @suaveplan/react-auth-whitelabel - White-label authentication React components with tenant branding wired through @suaveplan/react-ui runtime theme mutator

White-label authentication React components with tenant branding wired
through the `@suaveplan/react-ui` runtime theme-token mutator.

<!-- begin:auto-docs -->
## Documentation tree

- [login-form](./src/components/login-form/login-form.md) — `<LoginForm>` is the white-label login surface consumed by every tenant in the stack. It renders a controlled e…
  - [login-form](./src/components/login-form/login-form.md) — `<LoginForm>` is the white-label login surface consumed by every tenant in the stack. It renders a controlled e…
- [password-reset-form](./src/components/password-reset-form/password-reset-form.md) — `<PasswordResetForm>` is the white-label password-reset surface. It owns a single state machine across two modes — `req…
  - [password-reset-confirm](./src/components/password-reset-form/password-reset-confirm.md) — `PasswordResetConfirm` is the confirm-mode body of `<PasswordResetForm>` — the screen the user lands on from the email…
  - [password-reset-form](./src/components/password-reset-form/password-reset-form.md) — `<PasswordResetForm>` is the white-label password-reset surface. It owns a single state machine across two modes — `req…
  - [password-reset-request](./src/components/password-reset-form/password-reset-request.md) — `PasswordResetRequest` is the request-mode body of `<PasswordResetForm>` — the screen the user lands on when they click…
  - [password-reset-success](./src/components/password-reset-form/password-reset-success.md) — `PasswordResetSuccess` is the success state of `<PasswordResetForm>`, shared between the request and confirm modes. It…
- [register-form](./src/components/register-form/register-form.md) — `<RegisterForm>` is the white-label self-registration surface. It renders the header (logo + title + subtitle), the inl…
  - [register-form-fields](./src/components/register-form/register-form-fields.md) — `RegisterFormFields` is the inner field block of `<RegisterForm>` — name (optional, optionally required), email, passwo…
  - [register-form-terms](./src/components/register-form/register-form-terms.md) — `RegisterFormTerms` is the terms-acceptance checkbox block of `<RegisterForm>`. It renders the acceptance checkbox, the…
  - [register-form](./src/components/register-form/register-form.md) — `<RegisterForm>` is the white-label self-registration surface. It renders the header (logo + title + subtitle), the inl…
- [auth-context](./src/context/auth-context.md) — `auth-context.tsx` ships the `<AuthProvider>` React context provider together with the three hooks `useAuth`, `useUser`…
- [auth-http](./src/context/auth-http.md) — `auth-http.ts` houses the three helpers every `AuthProvider` verb shares: `resolveFetch`, `resolveNavigate`, and `postJ…
- [branding-context](./src/context/branding-context.md) — `branding-context.tsx` ships the `<BrandingProvider>` React context provider together with the hooks `useBranding`, `us…
- [error-codes](./src/errors/error-codes.md) — `error-codes.ts` registers the canonical, stable error-code registry used by every error thrown from `@suaveplan/react-…
- [react-auth-whitelabel-error](./src/errors/react-auth-whitelabel-error.md) — `ReactAuthWhitelabelError` is the canonical error class for every error thrown by `@suaveplan/react-auth-whitelabel`. I…
- [types](./src/types/branding.schema.md) — `TenantBrandingSchema` is the Zod schema that validates every `TenantBranding` payload entering the package from an unt…
  - [branding.schema](./src/types/branding.schema.md) — `TenantBrandingSchema` is the Zod schema that validates every `TenantBranding` payload entering the package from an unt…
- [utils](./src/utils/navigate-or-call.md) — `navigateOrCall(target)` is the canonical helper used by every form component in this package to act on a "URL or click…
  - [navigate-or-call](./src/utils/navigate-or-call.md) — `navigateOrCall(target)` is the canonical helper used by every form component in this package to act on a "URL or click…
<!-- end:auto-docs -->

## What ships

- **Forms** — `LoginForm`, `RegisterForm`, `PasswordResetForm`
- **Contexts** — `AuthProvider`, `BrandingProvider`
- **Hooks** — `useAuth`, `useBranding`, `useIsAuthenticated`, `useLogo`,
  `useTenantBranding`, `useUser`
- **Types** — `AuthConfig`, `AuthContextValue`, `AuthUser`,
  `BrandingContextValue`, `BrandingProviderProps`, `RegisterData`,
  `TenantBranding`, `TenantBrandingSchema`
- **Errors** — `REACT_AUTH_WL_CODES` + `ReactAuthWhitelabelError`

## Quick start

`BrandingProvider` calls `useThemeMutator()` from
`@suaveplan/react-ui/theme`. That hook MUST be invoked inside a
`<ThemeProvider>`. Wrap your subtree like this:

```tsx
import { ThemeProvider, lightTheme } from "@suaveplan/react-ui/theme";
import {
    AuthProvider,
    BrandingProvider,
    LoginForm,
} from "@suaveplan/react-auth-whitelabel";

<ThemeProvider themes={[lightTheme]} defaultTheme="light">
    <BrandingProvider
        brandingEndpoint="/api/branding"
        tenantId={tenantSlug}
    >
        <AuthProvider config={{ authUrl: "/api/auth" }}>
            <LoginForm
                onForgotPassword={() => router.push("/forgot")}
                onRegister={() => router.push("/register")}
            />
        </AuthProvider>
    </BrandingProvider>
</ThemeProvider>;
```

On every branding change, `BrandingProvider` writes `--brand-primary`,
`--brand-secondary`, `--brand-accent`, and `--brand-font` to
`document.documentElement.style` via
`useThemeMutator().setExtensionTokens(...)`. Cleanup is automatic on
unmount.

## Modules

- [`src/components/login-form/login-form.md`](./src/components/login-form/login-form.md)
- [`src/components/register-form/register-form.md`](./src/components/register-form/register-form.md)
- [`src/components/register-form/register-form-fields.md`](./src/components/register-form/register-form-fields.md)
- [`src/components/register-form/register-form-terms.md`](./src/components/register-form/register-form-terms.md)
- [`src/components/password-reset-form/password-reset-form.md`](./src/components/password-reset-form/password-reset-form.md)
- [`src/components/password-reset-form/password-reset-request.md`](./src/components/password-reset-form/password-reset-request.md)
- [`src/components/password-reset-form/password-reset-confirm.md`](./src/components/password-reset-form/password-reset-confirm.md)
- [`src/components/password-reset-form/password-reset-success.md`](./src/components/password-reset-form/password-reset-success.md)
- [`src/context/auth-context.md`](./src/context/auth-context.md)
- [`src/context/auth-http.md`](./src/context/auth-http.md)
- [`src/context/branding-context.md`](./src/context/branding-context.md)
- [`src/types/branding.schema.md`](./src/types/branding.schema.md)
- [`src/errors/error-codes.md`](./src/errors/error-codes.md)
- [`src/errors/react-auth-whitelabel-error.md`](./src/errors/react-auth-whitelabel-error.md)

## Out of scope (Excluded)

- MFA / passkey / WebAuthn flows — deferred until `@suaveplan/webauthn`
  - `@suaveplan/otp` ship .
- Magic-link / SMS OTP — depends on `@suaveplan/security-codes` /
  `@suaveplan/emailer` / `@suaveplan/sms`.
- Better-Auth first-class adapter — overlaps with the concurrent
  `@suaveplan/react-auth` Wave 1.
- Audit-log integration, password-strength meter, rate limiter, axe-core
  story gate — depend on packages not yet .
- Bundle-size snapshot — repo-wide tooling not yet wired.
- Playwright E2E specs — see `e2e/README.md`.