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

useBusinessUnitRead the active company (associates, available roles, addresses).

import { useBusinessUnit } from "@evolve-storefront/feature-organization/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 useBusinessUnit()

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

useBusinessUnitAddressesOne page of the active company's address book.

import { useBusinessUnitAddresses } from "@evolve-storefront/feature-organization/hooks";

data is a page ({ items, pagination }), not an array — a company's book cannot be handed over whole, so a caller rendering one page has to say so. Feed it straight to commerce-ui's AddressBook, which reads a company's book and a person's through the same props.

Auth-gated, so it reports isPending (never isLoading) until the session is established, and disabled without a business unit — the book hangs off BusinessUnit, so a personal session has none to read. The id is read softly for that reason: a render must be able to happen before the unit is known, which is the normal case wherever it comes from a token rather than a route segment.

function useBusinessUnitAddresses(options?: UseBusinessUnitAddressesOptions)

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.

useApprovalQueueOne page of the active business unit's approval queue, for ApprovalQueue.

import { useApprovalQueue } from "@evolve-storefront/feature-organization/approval/hooks";

function useApprovalQueue(args?: { status?: ApprovalStatus | undefined; page?: number | undefined; pageSize?: number | undefined; })

Option	Type	Description
status?	ApprovalStatus	Show only this status; omit for every status.
page?	number
pageSize?	number

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

useApprovalRuleOne approval rule of the active business unit, for ApprovalRuleForm on its edit page.

import { useApprovalRule } from "@evolve-storefront/feature-organization/approval/hooks";

function useApprovalRule(id: string)

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

useApprovalRulesOne page of the active business unit's approval rules, for ApprovalRuleList.

import { useApprovalRules } from "@evolve-storefront/feature-organization/approval/hooks";

function useApprovalRules(args?: { status?: ApprovalRuleStatus | undefined; page?: number | undefined; pageSize?: number | undefined; })

Option	Type	Description
status?	ApprovalRuleStatus	Only active or only inactive rules; omit for both.
page?	number
pageSize?	number

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

Changing data

useInviteAssociateInvite a new associate by email + roles.

import { useInviteAssociate } from "@evolve-storefront/feature-organization/hooks";

function useInviteAssociate()

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

useRemoveAssociateRemove an associate from the company.

import { useRemoveAssociate } from "@evolve-storefront/feature-organization/hooks";

function useRemoveAssociate()

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

useSetActiveBusinessContextSwitch the active company.

import { useSetActiveBusinessContext } from "@evolve-storefront/feature-organization/hooks";

Named for what the shopper does, not for the mutation behind it — the schema calls that businessUnitSwitch since framework 0.5.0.

function useSetActiveBusinessContext()

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

useSetDefaultCompanyAddressAction"Set as default" as an entry for a company address card's ActionsMenu: actions={[useSetDefaultCompanyAddressAction({ addressId, isDefault }), …]}.

import { useSetDefaultCompanyAddressAction } from "@evolve-storefront/feature-organization/hooks";

function useSetDefaultCompanyAddressAction(
  options: { addressId: string; isDefault?: boolean | undefined; },
): MenuAction

Option	Type	Description
addressId	string
isDefault?	boolean	The address already is the default, so there is nothing to set.

Returns MenuAction

useUpdateAssociateRolesReplace an associate's roles.

import { useUpdateAssociateRoles } from "@evolve-storefront/feature-organization/hooks";

function useUpdateAssociateRoles()

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

Other hooks

useCompanyAddressesThe company address-book mutations.

import { useCompanyAddresses } from "@evolve-storefront/feature-organization/hooks";

function useCompanyAddresses(): { add: UseMutationResult<BusinessUnit, Error, AddressInput, unknown>; update: UseMutationResult<BusinessUnit, Error, { addressId: string; address: AddressInput;…

useInviteAssociateFormReads the state seeded by InviteAssociateForm.

import { useInviteAssociateForm } from "@evolve-storefront/feature-organization/invite-associate-form";

function useInviteAssociateForm(): InviteAssociateFormContextValue

Returns InviteAssociateFormContextValue

useEditRolesFormReads the state seeded by EditRolesForm.

import { useEditRolesForm } from "@evolve-storefront/feature-organization/edit-roles-form";

function useEditRolesForm(): EditRolesFormContextValue

Returns EditRolesFormContextValue

useCompanyAddressFormThe logic behind the company address form: runs the create or the update from useCompanyAddresses, seeds defaultValues when editing, maps the typed backend errors by code through @evolve-storefront/errors, and returns the props commerce-ui's AddressForm takes.

import { useCompanyAddressForm } from "@evolve-storefront/feature-organization/company-address-dialog";

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 useCompanyAddressForm(
  options?: UseCompanyAddressFormOptions,
): UseCompanyAddressFormResult

Option	Type	Description
address?	Address	The address being edited. Provide it to update, omit it to add — the same switch CompanyAddressDialog uses, so the mode can't disagree with the id.
name?	string	The address's own name, such as "Warehouse". An empty string clears it. Omit it to keep the name the edited address has.
onAddressSaved?	(() => void)	Called after the add/update succeeds (e.g. close the dialog).

Returns UseCompanyAddressFormResult

useApprovalActionsApprove or reject an order's approval flow.

import { useApprovalActions } from "@evolve-storefront/feature-organization/approval/hooks";

function useApprovalActions(): { approve: UseMutationResult<OrderApproval, Error, Decision, unknown>; reject: UseMutationResult<OrderApproval, Error, Decision, unknown>; }

Returns { approve: UseMutationResult<OrderApproval, Error, Decision, unknown>; reject: UseMutationResult<OrderApproval, Error, Decision, unknown>; }

useApprovalRuleActionsCreate a rule, change one, or switch one on or off.

import { useApprovalRuleActions } from "@evolve-storefront/feature-organization/approval/hooks";

function useApprovalRuleActions(): { create: UseMutationResult<ApprovalRule, Error, ApprovalRuleCreateInput, unknown>; update: UseMutationResult<ApprovalRule, Error, { rule: RuleRef; input: Parti…

useApprovalRuleFormThe state behind ApprovalRuleForm: a draft of rule, or of a new rule without one, its errors once a save was tried, and saving it.

import { useApprovalRuleForm } from "@evolve-storefront/feature-organization/approval/hooks";

function useApprovalRuleForm(
  args: { rule?: ApprovalRule | undefined; customFields?: readonly ApprovalCustomField[] | undefined; onSaved?: ((rule: ApprovalRule) => void) | undefined; },
): { draft: RuleDraft; setDraft: Dispatch<SetStateAction<RuleDraft>>; errors: RuleDraftErrors; save: () => void; isPending: boolean; error: Error | null; }

Option	Type	Description
rule?	ApprovalRule
customFields?	readonly ApprovalCustomField[]
onSaved?	((rule: ApprovalRule) => void)

Returns { draft: RuleDraft; setDraft: Dispatch<SetStateAction<RuleDraft>>; errors: RuleDraftErrors; save: () => void; isPending: boolean; error: Error | null; }