Every UI component in this registry (SignInForm, SignUpForm, ForgotPasswordForm, ResetPasswordForm, VerifyEmail, MagicLinkCallback, TwoFactorChallenge, TwoFactorSetup, PasskeyList and AddPasskey, UserButton, AccountSettings and its seven sections, ConfirmEmailChange, OrganizationSwitcher, OrganizationMembers, OrganizationInvitations, AdminUsersTable, AdminUserDetail, ImpersonationBanner, SecurityKeys, TaskSetupMFA, OrganizationDomains, DomainSuggestions, and PasswordStrength, which has no onSuccess) is customised the same way. Learn it once here; each component's own section in the component reference lists only its slot names, its text key, its result, the errors it shows and its extra props. The hooks the components are built on are in React hooks.
- One provider.
<AuthProvider client={auth}>near the root. It carries the client, the query cache, the app'snavigateandLink, thepathsthe components link to,baseURL, and app-widelocalization. - Methods follow the client. A component shows a sign-in method only when its plugin is in the client's
pluginslist (usePlugin,usePluginClient), and OAuth buttons only for the providers the server lists. There are noshowPasskey-style props to keep in sync with the server. classNamestyles the root, merged after the defaults with tailwind-merge, somax-w-mdreplacesmax-w-sminstead of fighting it.classNames={{ slot: "..." }}styles a named part. Each component exports its slot union (SignInFormSlot), so a misspelt slot does not compile. Slots are merged the same way.localizationreplaces text. Each component exports its text type (SignInFormText) and English defaults (SIGN_IN_FORM_TEXT). Precedence: the component'slocalizationprop, then the provider'slocalization.<key>(signInForm), then the defaults.{name}placeholders are filled withformat.- Errors are messages by code. A failed call shows
localization.errors[code]from the provider if set, else the server's message (already translated when the server has a catalogue), else the code's declared English message. The client's own codes (client.network_error, ...) always get a friendly message. Codes are the closedAuthErrorCode | ClientErrorCodeunion, so an override for a code that does not exist is a compile error. - Success is a callback or a redirect.
onSuccess(result)replaces navigation; without it the component navigates toredirectTo, else to the provider's path for the flow (paths.afterSignIn).redirectTois read throughuseSafeRedirect: a value that is not a path on this site (or an origin inallowedRedirectOrigins) is treated as absent, because it usually comes from the address bar. Hand-offs to another step have their own callback (onSecondFactor) with the same fallback rule (paths.twoFactor). - Server state is TanStack Query. The session is one query (
useSession); every component that changes who is signed in callsrefreshSession()fromuseSessionActions, andsignOut()clears every auth entry. NouseEffectfetching. - Look: shadcn tokens, compact density. Colours come only from the shadcn CSS variables (
bg-card,text-muted-foreground, ...), so light and dark follow the app's theme. The registry's primitives are shadcn's Base UI ones at the ubgo density: 13px text,h-7controls,h-8for a form's main button. An app that keeps its own shadcn primitives gets the same components at its own density. - Accessible by default. Every input has a visible label; errors are linked with
aria-describedbyand markedaria-invalid; form errors arerole="alert"; a failed submit moves focus to the first invalid field; the main button is disabled andaria-busywhile its call runs; icons arearia-hidden; everything is reachable by keyboard and Enter submits.
AuthComponentProps<Slot, Key, Result> from @ubgo/auth-react is the base of every component's props:
| Prop | Type | What it does |
|---|---|---|
className |
string |
Classes for the root, merged after the defaults |
classNames |
Partial<Record<Slot, string>> |
Classes per named part |
localization |
Partial<ComponentLocalizations[Key]> |
Text overrides for this one use |
onSuccess |
(result: Result) => void |
Called after success, instead of navigating |
redirectTo |
string |
Where to go after success when there is no onSuccess; read through useSafeRedirect, so only a path on this site (or an allowed origin) is followed |
headingLevel |
1 to 6, default 1 |
The level of the component's title; pass 2 when the page has its own h1 |
| Prop | Default | What it does |
|---|---|---|
client |
required | The client from createAuthClient |
baseURL |
"/auth" |
The same baseURL the client was created with; needed for flows that are page navigations (OAuth start) |
queryClient |
the app's QueryClientProvider, else a private one |
The cache the session lives in |
navigate |
location.assign |
Client-side navigation, such as (href) => router.navigate({ href }) |
Link |
<a> |
The app's link component, { href, className, children } |
paths |
DEFAULT_AUTH_PATHS: signIn /sign-in, signUp /sign-up, forgotPassword /forgot-password, twoFactor /two-factor, setupTwoFactor /setup-two-factor, account /account, afterSignIn /, afterSignOut /sign-in |
Where the components send people; each key is overridable on its own |
localization |
none | { errors: { [code]: string }, signInForm: { ... }, ... } |
The provider memoises its value on client, baseURL, the query client, navigate, Link, paths and localization. Pass stable values: an inline paths={{ signIn: "/login" }} or navigate={(href) => ...} is a new object on every render of the component that mounts the provider, and re-renders every auth component and hook below it each time. Hoist constant objects to module scope and wrap navigate in useCallback, as the demo's shell does.
<AuthProvider
client={auth}
localization={{
errors: { "password.invalid_credentials": "E-Mail oder Passwort ist falsch." },
signInForm: { title: "Anmelden", submit: "Anmelden", identifierLabel: "E-Mail" },
}}
>Where a part is commonly replaced, a component takes a prop for it rather than a full render-prop tree: providerIcons on SignInForm replaces the mark on any provider's button. Anything beyond that is the reason the components are copied in: the file is yours, edit it.
Every component is two files. The view (sign-in-form-view.tsx, exporting SignInFormView) is pure presentation: values, pending and error state, text, links and callbacks come in as props, events go out (onSubmit(values), onPasskey(), onProvider(id)), and it imports nothing from this package, TanStack Query or a router. The wired component (sign-in-form.tsx, SignInForm) is the view connected to this package: the calls, the session, error messages by code, localization and navigation. The wired file re-exports the view's text, slot and value types, so importing from it keeps working. test/views-guard.test.ts fails when a view module imports the data layer. To put the screens on another API (the views alone, a translating fetch, or an adapter object as client), read Put the React UI on another API.
The package imports types and factories from @ubgo/auth-client. An app that generates its own client (myapp auth client ts --out web/src/auth) points that name at its folder, in tsconfig.json ("paths": { "@ubgo/auth-client": ["./src/auth/index.ts"] }) and in the bundler (resolve.alias).