Skip to Content

Client and React

Use the browser authentication client, React provider and hooks, forms, MFA settings, and configurable auth experience.

The @puzzle-ui/fullstack/auth/client entry point is browser-safe. AuthProvider shares one client and an authentication snapshot with descendants; session credentials remain managed by the server rather than browser storage.

Stable API maturity: Stable. The documented React auth components and Fullstack client APIs are covered by tests and are intended to remain backward-compatible within a major version. This is an API commitment, not a guarantee of production readiness in every application.

Install

Follow the Auth tutorial to combine these components with server enforcement. Its stricter provisioning-secret boundary uses non-hydrated server HTML instead of the bundled TOTP enrollment/settings UI.

npm install @puzzle-ui/fullstack react react-dom

React and React DOM 19 are required peer dependencies. The UI is built with @puzzle-ui/ui; that dependency is installed with the package.

Quick start

import { AuthProvider, useAuth, useSession, useUser } from "@puzzle-ui/fullstack/auth/client";

export const Providers = ({ children }: { children: React.ReactNode }) => (
  <AuthProvider options={{ basePath: "/api/auth" }} locale="en">
    {children}
  </AuthProvider>
);

export const Account = () => {
  const session = useSession();
  const user = useUser();
  const { signOut } = useAuth();

  if (session.isLoading) return <p>Loading…</p>;
  if (!user) return <p>Signed out</p>;

  return <button onClick={() => void signOut()}>Sign out {user.email}</button>;
};

useAuth must be called below AuthProvider; it exposes the client, snapshot, messages, state flags, refresh, and auth/lifecycle actions. useSession returns the status, optional MFA state, and loading/authenticated flags. useUser returns the current public user or null.

Client options and provider props

createAuthClient accepts AuthClientOptions. Its default base path is /api/auth, and its default fetch credentials mode is same-origin.

OptionTypeDefaultDescription
basePathstring"/api/auth"Absolute same-origin URL path prefix for the server endpoints. Query strings, fragments, and protocol-relative paths are rejected.
credentials"same-origin" | "include""same-origin"Fetch credentials mode for auth requests.
fetchertypeof fetchfetchFetch implementation used to call the server.

AuthProvider accepts these props:

PropTypeDefaultDescription
childrenReactNode—Descendant UI that can access auth context.
clientAuthClientCreated from optionsSupply an existing client instead of letting the provider create one.
optionsAuthClientOptions—Options for the provider-created client.
initialSnapshotAuthClientSnapshot—Initial public snapshot, useful when the server already loaded auth state.
localestring"en"Locale identifier used to resolve messages. English is the built-in fallback.
messagesAuthMessageOverrides—Partial per-message overrides.
onAuthStateChange(snapshot: AuthClientSnapshot) => void—Called when the provider observes an updated snapshot.

React components

All components below are exported from the client entry point and require an AuthProvider ancestor.

ComponentPurposeNotable props
SignInFormEmail/password sign-in form.className, redirectTo, onSuccess, onForgotPassword, onSignUp
SignUpFormRegistration form.className, redirectTo, onSuccess, onSignIn
MfaChallengeFormHandles the pending MFA challenge.className, redirectTo, onSuccess
AuthScreenSelects sign-in or sign-up UI and supports custom children.mode ("sign-in" or "sign-up"), children, className, callbacks, redirectTo
MfaSettingsManage the signed-in user's MFA factors and recovery codes.className

redirectTo values are restricted to safe, same-origin paths. If no redirect is supplied, use the callbacks or render your own navigation.

Configurable auth experience

AuthExperience combines branded sign-in/sign-up UI and custom registration fields. It displays the MFA challenge when sign-in requires another factor. Use onSubmit when the app must persist additional field values itself; custom fields are not added to the auth user model automatically.

import { AuthExperience } from "@puzzle-ui/fullstack/auth/client";

export const Register = () => (
  <AuthExperience
    mode="sign-up"
    config={{
      branding: { title: "Create your account" },
      redirects: { afterSignUp: "/dashboard" },
      fields: [
        {
          name: "company",
          label: "Company",
          type: "text",
          required: true,
          validate: (value) => (value ? null : "Enter your company."),
        },
      ],
    }}
    onSubmit={async ({ registration, fields, signUp }) => {
      const snapshot = await signUp(registration);
      await saveCompany(registration.email, fields.company);
      return snapshot;
    }}
  />
);
ConfigurationTypeDescription
mode"sign-in" | "sign-up"Form mode; defaults to "sign-in".
brandingAuthExperienceBrandingOptional logo, title, and description React nodes.
layoutAuthExperienceLayoutOptional class names, header/footer, width ("sm", "md", "lg", "full"), and alignment ("left", "center").
redirectsAuthExperienceRedirectsOptional afterSignIn and afterSignUp paths. Only safe root-relative paths are followed.
fieldsreadonly AuthCustomField[]Additional sign-up fields of type text, email, tel, url, number, checkbox, select, or textarea.
offerPasskeyAfterSignInbooleanDefaults to false. After successful sign-in, offer passkey enrollment before onSuccess and afterSignIn. Unsupported browsers and users with an existing passkey continue immediately.
onSubmit(input: AuthExperienceSubmitInput) => Promise<AuthClientSnapshot>Custom registration flow; receives standard registration values, custom field values, and the normal signUp action.
onSuccess, onSignIn, onSignUp, onForgotPassword() => voidOptional flow callbacks.

Custom field names must start with a letter, contain only letters, digits, _ or -, and must not use reserved names (name, email, password, confirmPassword). select fields use AuthFieldOption entries. Validation may be synchronous or asynchronous and should return a message for invalid values.

To offer a passkey after login, set config={{ offerPasskeyAfterSignIn: true, redirects: { afterSignIn: "/dashboard" } }}. The user can choose Skip for now or confirm their current password and register a browser passkey. Enrollment errors remain visible and do not prevent skipping. After registration, any new recovery codes remain visible until the user chooses Continue. The login password is not reused or stored. MFA challenges must complete before this optional step; sign-up is unchanged. The optional messages passkeyOfferDescription, passkeyAdded, and skip can be localized through AuthProvider.messages.

Localization and passkeys

English is built in. getAuthLocale selects a configured locale or falls back to English; resolveAuthMessages merges English defaults, locale messages, and per-message overrides. AuthMessages describes the complete message set and AuthMessageOverrides is a partial override. AuthProvider.messages supports per-message overrides.

isPasskeySupported checks browser credential APIs. startPasskeyRegistration and startPasskeyAuthentication validate the server-provided WebAuthn challenge and invoke the browser ceremony. createPasskeyBrowserHelpers allows injecting a PasskeyBrowserAdapter for testing or platform-specific integration. Use these through the client methods where possible; the server must verify every assertion and registration.

Client API

AuthClient provides register, signIn, signOut, and getSnapshot; TOTP/recovery-code/passkey challenge verification; required and optional MFA enrollment; factor listing/removal and recovery-code regeneration; step-up verification; and email/password lifecycle methods. MFA and lifecycle actions return the typed snapshots/results in shared types. Errors from failed HTTP responses are represented by AuthClientError, which includes status and code.

Accessibility and security

The forms use semantic form controls and Puzzle UI field components. Preserve their labels and visible validation feedback when styling them. A browser snapshot is public UI state, not authorization: protect data and actions on the server with @puzzle-ui/auth and @puzzle-ui/session. Never store session credentials in local storage or trust client-supplied identity data.

Exports

Runtime exports: AuthClientError, createAuthClient, createPasskeyBrowserHelpers, isPasskeySupported, startPasskeyRegistration, startPasskeyAuthentication, AuthProvider, useAuth, useSession, useUser, SignInForm, SignUpForm, MfaChallengeForm, AuthScreen, MfaSettings, AuthExperience, getAuthLocale, and resolveAuthMessages.

Type exports: AuthClient, AuthClientStatus, AuthClientUser, AuthClientOptions, AuthClientSnapshot, AuthClientMfaState, AuthClientSignInInput, AuthClientRegisterInput, AuthClientMfaFactor, AuthClientTotpEnrollment, AuthClientEnrollmentResult, AuthClientRecoveryCodesResult, AuthClientFactorList, PasskeyBrowserAdapter, PasskeyBrowserHelpers, AuthProviderProps, AuthContextValue, AuthFormProps, SignInFormProps, SignUpFormProps, MfaChallengeFormProps, AuthScreenProps, MfaSettingsProps, AuthExperienceProps, AuthExperienceConfig, AuthExperienceBranding, AuthExperienceLayout, AuthExperienceRedirects, AuthCustomField, AuthFieldOption, AuthFieldValue, AuthFieldValues, AuthRegistrationInput, AuthExperienceSubmitInput, AuthLocale, AuthMessages, and AuthMessageOverrides.

For server wiring, continue to Server handlers or use a framework adapter.