feature-account 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

useAccountRead the signed-in customer (profile + addresses).

import { useAccount } from "@evolve-storefront/feature-account/hooks";

Gated on auth, so it reports isPending (not isLoading) until the client auth context validates. Render the skeleton while isPending; only isSuccess && !data is a real 404.

function useAccount()

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

useCustomerAddressesOne page of the signed-in customer's address book.

import { useCustomerAddresses } from "@evolve-storefront/feature-account/hooks";

data is a page ({ items, pagination }), not an array — a person's book is paged for the same reason a company's is, so a caller rendering one page has to say so. Feed it straight to commerce-ui's AddressBook, which reads both books.

Auth-gated, so it reports isPending (never isLoading) until the session is established. isSuccess && !data is a customer the server has no book for, which is a state to render rather than a 404.

function useCustomerAddresses(options?: UseCustomerAddressesOptions)

Option	Type	Description
`page?`	`number`	1-based. Defaults to the first page.
`pageSize?`	`number`	Defaults to the server's 20.
`searchTerm?`	`string \| null`	Narrows the book by name, company, street, postal code, city or region; every word must appear, in any order. The server matches, so nothing is filtered client-side and a term is a round trip.

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

Changing data

useAddAddressAdd an address to the address book.

import { useAddAddress } from "@evolve-storefront/feature-account/hooks";

function useAddAddress()

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

useDeleteAccountDelete the account (optional consumer capability).

import { useDeleteAccount } from "@evolve-storefront/feature-account/hooks";

function useDeleteAccount()

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

useRemoveAddressRemove an address.

import { useRemoveAddress } from "@evolve-storefront/feature-account/hooks";

function useRemoveAddress()

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

useSetDefaultAddressMark an address as the default shipping and/or billing address.

import { useSetDefaultAddress } from "@evolve-storefront/feature-account/hooks";

function useSetDefaultAddress()

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

useSetDefaultAddressAction"Set as default" as an entry for an address card's ActionsMenu, rather than a button of its own: actions={[useSetDefaultAddressAction({ addressId }), …]}.

import { useSetDefaultAddressAction } from "@evolve-storefront/feature-account/hooks";

function useSetDefaultAddressAction(
  options: { addressId: string; kind?: "shipping" | "billing" | "both" | undefined; isDefault?: boolean | undefined; },
): MenuAction

Option	Type	Description
`addressId`	`string`
`kind?`	`"shipping" \| "billing" \| "both"`	Which default to set. `"both"` sets shipping and billing in one call.
`isDefault?`	`boolean`	The address already is that default, so there is nothing to set.

Returns MenuAction

useUpdateAddressEdit an existing address.

import { useUpdateAddress } from "@evolve-storefront/feature-account/hooks";

function useUpdateAddress()

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

useUpdateEmailChange the sign-in email; requires the current password.

import { useUpdateEmail } from "@evolve-storefront/feature-account/hooks";

function useUpdateEmail()

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

useUpdateNotificationPreferencesUpdate the shopper's marketing opt-ins, such as the newsletter.

import { useUpdateNotificationPreferences } from "@evolve-storefront/feature-account/hooks";

function useUpdateNotificationPreferences()

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

useUpdatePasswordChange the password; requires the current password.

import { useUpdatePassword } from "@evolve-storefront/feature-account/hooks";

function useUpdatePassword()

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

useUpdateProfileUpdate the shopper's personal details (name, salutation) — decoupled from the address book.

import { useUpdateProfile } from "@evolve-storefront/feature-account/hooks";

function useUpdateProfile()

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

Other hooks

useAddressBookOne page of the signed-in shopper's address book, with its own search and page.

import { useAddressBook } from "@evolve-storefront/feature-account/hooks";

While a signed-in shopper's book loads, book is there and pending rather than absent, so a section shows the book's shape instead of a form it then replaces. An empty search result keeps the book, or the search box would go with it.

function useAddressBook(
  options?: { pageSize?: number | undefined; },
): UseAddressBookResult

Option	Type	Description
`pageSize?`	`number`

Returns UseAddressBookResult

useAddressFormThe logic behind the address form: runs useAddAddress or useUpdateAddress, seeds defaultValues when editing, maps the typed backend errors by code through @evolve-storefront/errors, and returns the props the AddressForm View takes.

import { useAddressForm } from "@evolve-storefront/feature-account/hooks";

One hook for add and edit, keyed on the address passed rather than a mode flag, so the mode can never disagree with the id.

function useAddressForm(options?: UseAddressFormOptions): UseAddressFormResult

Option	Type	Description
`address?`	`Address`	The address being edited. Provide it to update, omit it to add — the same switch `AddressDialog` uses, so the mode can't disagree with the id.
`makeDefault?`	`boolean`	Also make the saved address the default delivery address.
`name?`	`string`	The address's own name, such as "Work". An empty string clears it. Omit it to keep the name the edited address has.
`onAddressSaved?`	`((customer: Customer) => void)`	Called after the add/update succeeds (e.g. close the dialog).

Returns UseAddressFormResult

useChangeEmailFormThe logic behind the change-email form: runs useUpdateEmail, maps the typed backend errors by code through @evolve-storefront/errors (ValidationError.fields → per-field, the first concrete error → form-level), and hands back exactly the props the pure ChangeEmailForm View takes.

import { useChangeEmailForm } from "@evolve-storefront/feature-account/hooks";

The View stays presentational and independently storyable; this hook exists so the wiring is not re-implemented (and re-bugged) in every consumer. Drop to useUpdateEmail directly when you need behaviour this doesn't cover.

function useChangeEmailForm(
  options?: UseChangeEmailFormOptions,
): UseChangeEmailFormResult

Option	Type	Description
`onEmailChanged?`	`((customer: Customer) => void)`	Called after the email change succeeds (e.g. close a dialog, toast).

Returns UseChangeEmailFormResult

useChangePasswordFormThe logic behind the change-password form: runs useUpdatePassword, maps the typed backend errors by code through @evolve-storefront/errors (ValidationError.fields per field, the first other error form-level), and returns the props the ChangePasswordForm View takes.

import { useChangePasswordForm } from "@evolve-storefront/feature-account/hooks";

Use useUpdatePassword directly for behavior this does not cover.

function useChangePasswordForm(
  options?: UseChangePasswordFormOptions,
): UseChangePasswordFormResult

Option	Type	Description
`onPasswordChanged?`	`((customer: Customer) => void)`	Called after the password change succeeds (e.g. close a dialog, toast).

Returns UseChangePasswordFormResult

useProfileFormThe logic behind the personal-details form: runs useUpdateProfile, maps the typed backend errors by code through @evolve-storefront/errors, and hands back exactly the props the pure ProfileForm View takes.

import { useProfileForm } from "@evolve-storefront/feature-account/hooks";

Drop to useUpdateProfile directly when you need behaviour this doesn't cover; the View is unchanged either way.

function useProfileForm(options?: UseProfileFormOptions): UseProfileFormResult

Option	Type	Description
`onProfileSaved?`	`((customer: Customer) => void)`	Called after the profile update succeeds (e.g. close a dialog, toast).

Returns UseProfileFormResult

Get started

Guides

Conventions

Reference

Architecture

Changelog

feature-account hooks

Reading data

Changing data

Other hooks