Auth Pages
Eight pages for the whole credential lifecycle
Authentication on the backend gives you the routes; these eight pages give you the screens, so you almost never hand-build an auth form again. Each page takes the matching generated action as a prop, owns its form, validation, captcha and multi-step state machine, and calls your callbacks at the right moments. You provide routing and branding.
They cover the entire journey: LoginPage and RegisterPage for entry, ForgotPasswordPage → ResetPasswordPage for recovery, SetPasswordPage for invites and magic-link landings, ChangePasswordPage for signed-in users, and VerifyEmailPage / MagicLinkVerifyPage for the links your emails send. Password rules are enforced consistently by one PasswordPolicy engine with a live strength meter.
Everything shares the library contract — variant for layout, a theme you can extendXTheme(), a useXStore for state, and lifecycle callbacks. Wire the action, set a couple of links, and the page is production-ready.
Wiring an auth page#
The minimum is one action; everything else has a sensible default. Pages never navigate for you — they fire onSuccess so you stay in control of routing.
1import { LoginPage } from "nucleus-core/fe";2import { useApiActions } from "@/lib/api";3 4export default function Login() {5 const actions = useApiActions();6 return (7 <LoginPage8 variant="default" // 'default' | 'minimal' | 'split'9 loginAction={actions.LOGIN}10 meAction={actions.ME}11 logoutAction={actions.LOGOUT}12 captchaGenerateAction={actions.CAPTCHA_GENERATE}13 showRememberMe14 showForgotPassword15 forgotPasswordHref="/forgot-password"16 signUpHref="/register"17 onSuccess={() => router.push("/app")}18 />19 );20}variant'default' | 'minimal' | 'split'OptionalLayout shape shared by the auth pages — centered card, bare form, or split hero/form. Logic is identical across variants.
'default'logo / title / subtitleReactNode / stringOptionalBranding slots. Login also takes loggedInTitle/loggedInSubtitle for the already-signed-in state.
showBackground / className / themestylingOptionalToggle the built-in AbstractAnimatedBackground, add classes, or pass a theme from extendLoginPageTheme()/etc. to restyle.
onSuccess / onLogout / onForgotPassword / onSignUp() => voidOptionalLifecycle callbacks. The page does the API work and calls these so you own navigation. Link variants (forgotPasswordHref, signUpHref) are provided as an alternative to callbacks.
LoginPage#
Email/username + password sign-in with optional captcha and remember-me. Reads the LOGIN action and, optionally, ME (to render a signed-in state) and LOGOUT.
loginActionLoginActionOptionalRequired. payload is { email, password, rememberMe?, captchaId?, captchaAnswer? }; on success the cookies are set by the client and onSuccess fires.
meAction / logoutActionMeAction / LogoutActionOptionalSupply ME to let the page detect an existing session and show the logged-in panel; LOGOUT powers the sign-out button there.
captchaGenerateAction + config.login.captchaCaptchaAction + CaptchaConfigOptionalEnables the Captcha challenge on the form. The page requests a challenge and submits captchaId/captchaAnswer with the login payload.
showRememberMe / showForgotPassword / showSignUpbooleanOptionalToggle the secondary controls; pair with forgotPasswordHref / signUpHref or the onForgotPassword / onSignUp callbacks.
RegisterPage#
Sign-up with a live password-strength meter, optional name fields, profile creation and terms gating. Driven by the REGISTER action and a config.passwordPolicy.
registerActionRegisterActionOptionalRequired. payload is { email, password, firstName?, lastName?, createProfile? }.
config.passwordPolicyPasswordPolicyConfigOptionalRules enforced live, with the strength meter.
minLength / maxLengthnumberOptionalLength bounds for the password.
requireUppercase / requireLowercase / requireNumber / requireSpecialCharbooleanOptionalCharacter-class requirements checked as the user types.
specialCharsstringOptionalThe set of characters that count as 'special' for the rule above.
showStrengthIndicatorbooleanOptionalRender the PasswordStrengthIndicator (score + per-rule checklist). Exported standalone too.
config.registerRegisterFeatureConfigOptionalFeature toggles: showFirstName, showLastName, createProfileOnRegister, and termsUrl / privacyUrl for the consent links (with showTerms to require acceptance).
Password recovery & set#
The reset journey and the invite/magic-link landing. All four enforce a shared PasswordPolicy (the SetPassword engine adds preventCommonPasswords and preventUserInfoInPassword).
ForgotPasswordPageForgotPasswordActionOptionalCollects the email and triggers the reset mail. Steps: form → success. Pair with backToLoginHref.
ResetPasswordPageResetPasswordActionOptionalThe landing for the emailed reset token — validates the token, takes a new password (policy-checked) and confirms. Steps: verifying → form → success → error.
SetPasswordPagemagicLinkVerifyAction + passwordSetAction / passwordChangeActionOptionalDual-purpose: accepting an invite (isInvite) to set an initial password, or landing from a magic link. It verifies the token then sets the password. Takes the token as a prop and a passwordPolicy.
ChangePasswordPageChangePasswordActionOptionalFor an already-signed-in user — current + new + confirm, policy-checked. No token needed.
DEFAULT_PASSWORD_POLICYRequired<PasswordPolicy>OptionalThe exported baseline used when you don't pass one: minLength 8, maxLength 128, upper+lower+number required, special optional, preventCommonPasswords and preventUserInfoInPassword on, strength indicator shown.
Email verification & magic link#
The pages your transactional emails point at. Both consume a token from the URL, call their verify action and render the verifying / success / error states — minimal wiring, mostly presentation.
VerifyEmailPageVerifyEmailAction + ResendVerificationActionOptionalConfirms a new account's email from the token, and offers a resend when the token is expired. Steps: verifying → success → error.
MagicLinkVerifyPageMagicLinkVerifyActionOptionalCompletes a passwordless sign-in from a magic-link token, then hands off via onSuccess. Has its own extendable theme (magicLinkVerifyPageTheme).
Related sections