feature-auth hooks

The components already use these hooks. Reach for them when you build your own UI on the same data. Open a hook for its options and what it returns.

Reading data

useCustomerExistsCheck whether an account already exists for an email (optional) — used to steer register vs sign-in.

import { useCustomerExists } from "@evolve-storefront/feature-auth/hooks";

function useCustomerExists(email: string)

Returns A React Query result: data, isPending, error and the rest.

Changing data

useLoginAuthenticate with email + password → customerLogin.

import { useLogin } from "@evolve-storefront/feature-auth/hooks";

function useLogin()

Returns A React Query mutation: mutate, mutateAsync, isPending and the rest.

useLogoutLog out the current customer: through AuthProvider's logout where the app supplies it, so the refresh token is revoked at its own path, else customerLogout on the fetcher.

import { useLogout } from "@evolve-storefront/feature-auth/hooks";

function useLogout()

Returns A React Query mutation: mutate, mutateAsync, isPending and the rest.

useRegisterRegister a new customer → customerCreate.

import { useRegister } from "@evolve-storefront/feature-auth/hooks";

function useRegister()

Returns A React Query mutation: mutate, mutateAsync, isPending and the rest.

useRequestPasswordResetRequest a password-reset email → customerPasswordResetRequest.

import { useRequestPasswordReset } from "@evolve-storefront/feature-auth/hooks";

function useRequestPasswordReset()

Returns A React Query mutation: mutate, mutateAsync, isPending and the rest.

useResetPasswordSet a new password from a reset token → customerPasswordReset.

import { useResetPassword } from "@evolve-storefront/feature-auth/hooks";

function useResetPassword()

Returns A React Query mutation: mutate, mutateAsync, isPending and the rest.

Other hooks

useAdoptSessionMake the page the signed-in buyer's without leaving it: re-read the session, drop every cached answer (each was given to whoever was here before), then re-render on the server, which is still the anonymous render until asked again.

import { useAdoptSession } from "@evolve-storefront/feature-auth/hooks";

function useAdoptSession(
  options: AdoptSessionOptions,
): () => void

Option	Type	Description
`validateLocalToken`	`() => void`	Re-read the session cookie the gateway just set — `useAuth().validateLocalToken`.
`refresh`	`() => void`	Render the page again on the server for the new identity — `router.refresh`.
`onAdopted?`	`(() => void)`	What else changes hands with the session, such as merging the guest's cart.

Returns () => void

useAuthErrorMessagesAuth's resolve(code) for mapServerErrors: maps a backend error code (Tier-2 AuthenticationError/PasswordResetError codes and Tier-1 field codes) to a localized message from the Auth.errors namespace, with a mandatory fallback to Auth.errors.unknown.

import { useAuthErrorMessages } from "@evolve-storefront/feature-auth/hooks";

function useAuthErrorMessages(): ResolveErrorCode

Returns ResolveErrorCode

useCheckoutSignInThe checkout contact step's sign-in: an email that belongs to an account asks for its password, and the shopper may still continue as a guest.

import { useCheckoutSignIn } from "@evolve-storefront/feature-auth/hooks";

function useCheckoutSignIn(
  options: CheckoutSignInOptions,
): CheckoutSignInProps

Option	Type	Description
`onGuestEmail`	`(email: string) => void`	Record the email on the cart as a guest's — `feature-cart`'s customer email.
`onSignedIn`	`(customer: AuthCustomer) => void`	After signing in. A reload is the usual answer: the session and the cart merged into the account's both render from the request.

Returns CheckoutSignInProps

useLoginFormThe logic behind LoginForm: runs useLogin, maps the typed backend errors by code through the feature's Auth.errors namespace, and returns the props a form View takes.

import { useLoginForm } from "@evolve-storefront/feature-auth/hooks";

LoginForm uses this internally, so the standard path needs no wiring; it is exported for consumers composing their own auth UI around LoginFormView. Drop to useLogin directly for behaviour this doesn't cover.

function useLoginForm(options?: UseLoginFormOptions): UseLoginFormResult

Option	Type	Description
`onLoggedIn?`	`((customer: AuthCustomer) => void)`	Called after success, alongside the provider's session seam.

Returns UseLoginFormResult

usePasswordResetFormThe logic behind PasswordResetForm: runs useResetPassword, maps the typed backend errors by code through the feature's Auth.errors namespace, and returns the props a form View takes.

import { usePasswordResetForm } from "@evolve-storefront/feature-auth/hooks";

PasswordResetForm uses this internally, so the standard path needs no wiring; it is exported for consumers composing their own auth UI. Drop to useResetPassword directly for behaviour this doesn't cover.

function usePasswordResetForm(
  options: UsePasswordResetFormOptions,
): UsePasswordResetFormResult

Option	Type	Description
`token`	`string`	The reset token from the emailed link.
`onPasswordChanged?`	`((customer: AuthCustomer) => void)`	Called after success, alongside the provider's session seam.

Returns UsePasswordResetFormResult

usePasswordResetRequestFormThe logic behind PasswordResetRequestForm: runs useRequestPasswordReset, maps the typed backend errors by code through the feature's Auth.errors namespace, and returns the props a form View takes.

import { usePasswordResetRequestForm } from "@evolve-storefront/feature-auth/hooks";

PasswordResetRequestForm uses this internally, so the standard path needs no wiring; it is exported for consumers composing their own auth UI. Drop to useRequestPasswordReset directly for behaviour this doesn't cover.

function usePasswordResetRequestForm(
  options?: UsePasswordResetRequestFormOptions,
): UsePasswordResetRequestFormResult

Option	Type	Description
`onResetRequested?`	`(() => void)`	Called after success, alongside the provider's session seam.

Returns UsePasswordResetRequestFormResult

useRegisterFormThe logic behind RegisterForm: runs useRegister, maps the typed backend errors by code through the feature's Auth.errors namespace, and returns the props a form View takes.

import { useRegisterForm } from "@evolve-storefront/feature-auth/hooks";

RegisterForm uses this internally, so the standard path needs no wiring; it is exported for consumers composing their own auth UI. Drop to useRegister directly for behaviour this doesn't cover.

function useRegisterForm(
  options?: UseRegisterFormOptions,
): UseRegisterFormResult

Option	Type	Description
`onRegistered?`	`((customer: AuthCustomer) => void)`	Called after success, alongside the provider's session seam.

Returns UseRegisterFormResult

useReturningCustomerInline account detection for the checkout's email field.

import { useReturningCustomer } from "@evolve-storefront/feature-auth/hooks";

function useReturningCustomer(
  options: ReturningCustomerOptions,
): ReturningCustomer

Option	Type	Description
`onSignedIn`	`(customer: AuthCustomer) => void`	After signing in. A reload is the usual answer, so the merged cart renders.

Returns ReturningCustomer