embedded-react-sdk/docs/reference/hooks.md at main · Gusto/embedded-react-sdk

title	Hooks
description	Headless utilities that handle data fetching, form state, validation, and API submission — you own the layout, the SDK handles the business logic. For concepts and usage — the form vs. data hook distinction, connecting fields, error handling, and composition — see the Hooks guide.
sidebar_position	8
generated_by	typedoc
custom_edit_url

Headless utilities that handle data fetching, form state, validation, and API submission — you own the layout, the SDK handles the business logic. For concepts and usage — the form vs. data hook distinction, connecting fields, error handling, and composition — see the Hooks guide.

🌐 Data hooks

Hook	Description
useContractorDocumentsList	Standalone data hook for a contractor's documents.
useEmployeeList	Fetches a paginated list of a company's employees and decorates each entry with the actions allowed for its current onboarding state.

✍️ Form hooks

Hook	Description
useBankForm	Headless React Hook Form hook for creating an employee bank account.
useChildSupportGarnishmentForm	Headless hook for creating or updating a child-support garnishment.
useCompensationForm	Headless hook for creating or updating a compensation row on a job — FLSA classification, pay rate, payment unit, effective date, and optional minimum-wage adjustment.
useContractorAddressForm	Form hook for editing a contractor's address.
useContractorBankAccountForm	Headless React Hook Form hook for creating a contractor's bank account.
useContractorDetailsForm	Headless hook for creating or updating a contractor's profile details — individual vs. business type, wage type, names, SSN/EIN, work state, and the self-onboarding preference.
useContractorPaymentMethodForm	Headless React Hook Form hook for managing a contractor's payment method type.
useContractorSignatureForm	Headless hook for signing a contractor document — collects the document's fields plus a typed signature and consent.
useCurrentHomeAddressForm	Convenience wrapper around useHomeAddressForm that auto-resolves the employee's current home address.
useCurrentWorkAddressForm	Convenience wrapper around useWorkAddressForm that auto-resolves the employee's current work address.
useDeductionForm	Headless hook for creating or updating a non-child-support deduction.
useEmployeeDetailsForm	Headless hook for creating or updating an employee's profile details — name, email, SSN, date of birth, and self-onboarding preference.
useEmployeeStateTaxesForm	Headless form hook for updating an employee's state tax withholding answers. The set of questions is driven by the API response per state, so `form.Fields` is an array of state groups with discriminated, render-ready `Field` components rather than a fixed named object.
useFederalTaxesForm	Headless hook for updating an employee's federal tax (W-4) withholding information — filing status, multiple-jobs flag, dependents, other income, deductions, and extra withholding.
useHomeAddressForm	Form hook for creating or editing an employee's home address.
useJobForm	Headless hook for creating or updating an employee's job — title, hire date, S-Corp 2% shareholder flag, and Washington state workers' compensation fields.
usePaymentMethodForm	Headless React Hook Form hook for updating an employee's payment method.
usePayScheduleForm	Form hook for creating or updating a company pay schedule.
useSignCompanyForm	Headless hook for signing a company form — displays the form PDF and collects a typed signature with confirmation checkbox.
useSignEmployeeForm	Headless hook for signing an employee form — captures a typed signature, electronic consent, and (for I-9 forms) preparer/translator certification.
useSplitPaymentsForm	Headless React Hook Form hook for splitting an employee's Direct Deposit across multiple bank accounts.
useWorkAddressForm	Form hook for creating or editing an employee's work address.

SDKFormProvider

Provides form context to field components so they can read metadata, control, and error state without an explicit formHookResult prop on each field. Server-side field errors are automatically synced onto their corresponding fields.

Example

const formHookResult = useEmployeeDetailsForm({ employeeId })
const { Fields } = formHookResult.form

// SDKFormProvider supplies context only — wire up submission and render the
// <form> element yourself.
const handleSubmit = () =>
  formHookResult.actions.onSubmit({ onEmployeeUpdated: (emp) => { ... } })

return (
  <SDKFormProvider formHookResult={formHookResult}>
    <form onSubmit={handleSubmit}>
      <Fields.FirstName label="First name" />
      <Fields.LastName label="Last name" />
      <button type="submit">Save</button>
    </form>
  </SDKFormProvider>
)

Type Parameters

Type Parameter	Default type
`TFormData` extends `FieldValues`	`FieldValues`
`TFieldsMetadata` extends { [K in string \| number \| symbol]: FieldMetadata \| FieldMetadataWithOptions<unknown> }	`Record`<`string`, `FieldMetadata` \| `FieldMetadataWithOptions`<`unknown`>>

SDKFormProviderProps

Props for SDKFormProvider.

Property	Type	Description
`children`	`ReactNode`	Field components (or any content) that consume the provided form context.
`formHookResult`	`object`	The form hook result whose fields, metadata, and errors are shared with descendant field components.
`formHookResult.errorHandling`	`object`	-
`formHookResult.errorHandling.errors`	`SDKError`[]	-
`formHookResult.form`	`object`	-
`formHookResult.form.fieldsMetadata`	`TFieldsMetadata`	-
`formHookResult.form.hookFormInternals`	`HookFormInternals`<`TFormData`>	-

Form composition

Usage: Composing multiple hooks and Handling hook errors.

composeErrorHandler()

composeErrorHandler(sources: MixedErrorSource[], submitState?: SubmitStateForErrorHandling): HookErrorHandling

Merges multiple error sources into a single HookErrorHandling.

Remarks

Accepts any mix of @gusto/embedded-api-v-2026-06-15 React Query results and SDK hook results that already expose an errorHandling object (including the value returned by composeSubmitHandler). Query errors are normalized to SDKError, nested hook errors are flattened in, and an optional submit-state argument adds a submit error to the same list.

The returned retryQueries refetches every failed query and delegates into each nested hook so their retries fire too. clearSubmitError clears the optional submit state and delegates into each nested hook.

Pairs with composeSubmitHandler by name only — this composes error state and recovery, not a submit callback.

Example

import { composeErrorHandler, useEmployeeDetailsForm } from '@gusto/embedded-react-sdk'
import { useEmployeeFormsList } from '@gusto/embedded-api-v-2026-06-15/react-query/employeeFormsList'

function EmployeeProfileView({ companyId, employeeId }: { companyId: string; employeeId: string }) {
  const employeeDetails = useEmployeeDetailsForm({ companyId, employeeId })
  const formsListQuery = useEmployeeFormsList({ employeeId })

  const errorHandling = composeErrorHandler([employeeDetails, formsListQuery])

  if (errorHandling.errors.length > 0) {
    return (
      <div role="alert">
        {errorHandling.errors.map((error, i) => (
          <p key={i}>{error.message}</p>
        ))}
        <button onClick={errorHandling.retryQueries}>Retry</button>
      </div>
    )
  }

  return null
}

Parameters

Parameter	Type	Description
`sources`	`MixedErrorSource`[]	Error sources to merge. Each entry is either a React Query result or an object with an `errorHandling` property.
`submitState?`	`SubmitStateForErrorHandling`	Optional screen-level submit state to fold into the result.

Returns

HookErrorHandling

A single HookErrorHandling covering every source.

MixedErrorSource

MixedErrorSource = QueryWithRefetch | { errorHandling: HookErrorHandling; }

Accepted input shape for composeErrorHandler: either a React Query result (anything with error and refetch) or another SDK hook result that exposes an errorHandling object.

QueryWithRefetch

QueryWithRefetch = Pick<UseQueryResult, "error" | "refetch">

The subset of a TanStack Query result — its error and refetch — that composeErrorHandler reads from an additional query passed as a source.

SubmitStateForErrorHandling

SubmitStateForErrorHandling = object

Submit-side error state to merge into a composed HookErrorHandling.

Remarks

Pass to composeErrorHandler when a screen has its own submit state outside of any SDK form hook, so submit errors appear in the same error surface as query errors and can be cleared together with clearSubmitError.

Properties

Property	Type	Description
`setSubmitError`	(`error`: `SDKError` \| `null`) => `void`	Sets or clears the submit error.
`submitError`	`SDKError` \| `null`	The current submit error, or `null` when cleared.

composeSubmitHandler()

composeSubmitHandler<TForms>(forms: readonly [{ [K in string | number | symbol]: ComposeSubmitInput<TForms[K]> }], onAllValid: () => Promise<void>): ComposeSubmitHandlerResult

Coordinates validation and submission across multiple form hooks on the same page.

Remarks

Validates all forms simultaneously via handleSubmit(), then focuses the visually first invalid field across all forms (sorted by getBoundingClientRect()). Only calls onAllValid when every form passes.

Uses handleSubmit rather than trigger so that react-hook-form sets formState.isSubmitted = true, which enables reValidateMode (default: onChange). Without this, errors set by manual trigger() calls would never clear as the user types.

Each hook passed to forms should be initialized with shouldFocusError: false so that react-hook-form's built-in per-form focus is disabled and composeSubmitHandler can manage cross-form focus instead.

The returned errorHandling is the same shape every SDK hook returns, so the whole result can be passed back into composeErrorHandler when you need to add extra @gusto/embedded-api-v-2026-06-15 queries or screen-level submit state.

Example

const detailsForm = useEmployeeDetailsForm({ employeeId, shouldFocusError: false })
const addressForm = useHomeAddressForm({ employeeId, shouldFocusError: false })

const { handleSubmit, errorHandling } = composeSubmitHandler(
  [detailsForm, addressForm],
  async () => {
    await detailsForm.actions.onSubmit()
    await addressForm.actions.onSubmit()
  },
)

return <form onSubmit={handleSubmit}>...</form>

Type Parameters

Type Parameter	Description
`TForms` extends readonly `FieldValues`[]	Tuple of form value shapes, one per slot of `forms`.

Parameters

Parameter	Type	Description
`forms`	readonly [{ [K in string \| number \| symbol]: ComposeSubmitInput<TForms[K]> }]	Form hook results and/or raw `UseFormReturn` instances to coordinate.
`onAllValid`	() => `Promise`<`void`>	Async callback invoked once every form has passed validation.

Returns

ComposeSubmitHandlerResult

A ComposeSubmitHandlerResult with a unified handleSubmit and aggregated errorHandling.

ComposableFormHookResult

Minimal shape required for a form hook result to participate in composeSubmitHandler. Any hook returning BaseFormHookReady satisfies this interface.

formMethods is declared with method-call syntax (rather than reused from HookFormInternals) so TypeScript applies bivariant parameter checking, allowing hooks with specific form data generics to be passed without casts. _fieldElementRegistry is reused directly since its type doesn't depend on the form's generic.

Properties

Property	Type	Description
`errorHandling`	`HookErrorHandling`	The error-handling surface aggregated across the composed forms.
`form`	`object`	The form surface: the react-hook-form internals used to validate and focus fields.
`form.hookFormInternals`	`Pick`<`HookFormInternals`<`FieldValues`>, `"_fieldElementRegistry"`> & `object`	-

ComposeSubmitHandlerResult

Result returned by composeSubmitHandler: a single submit handler that coordinates validation across the composed forms, and aggregated error state.

Properties

Property	Type	Description
`errorHandling`	`HookErrorHandling`	Aggregated error state across all composed SDK form hooks. Pass to composeErrorHandler for screen-level error surfaces.
`handleSubmit`	(`e`: `SyntheticEvent`) => `Promise`<`void`>	Submit handler to pass to a form's `onSubmit`. Validates all composed forms before calling `onAllValid`.

ComposeSubmitInput

ComposeSubmitInput<T> = ComposableFormHookResult | UseFormReturn<T>

Accepted input for a single slot of composeSubmitHandler's forms array.

Remarks

SDK form hook results (anything matching ComposableFormHookResult) are composed directly.
A raw react-hook-form UseFormReturn<T> is supported for screen-local auxiliary forms that don't warrant a dedicated SDK hook. Raw forms contribute validation/focus behavior but no errorHandling (fields surface their own inline errors via react-hook-form).

Type Parameters

Type Parameter	Default type	Description
`T` extends `FieldValues`	`FieldValues`	The shape of the form values when a raw `UseFormReturn` is passed.

Common hook results

The shape every hook returns — see the Hooks overview.

BaseHookReady

Base ready-state shape for non-form hooks (data-fetching or action hooks without a form).

Remarks

Each concrete hook substitutes its own data and status shape via the type parameters so consumers see fully-typed payloads without manual narrowing. isLoading: false discriminates this branch from HookLoadingResult.

Extended by

UseEmployeeListReady

Type Parameters

Type Parameter	Default type	Description
`TData` extends `Record`<`string`, `unknown`>	`Record`<`string`, `unknown`>	Shape of the data the hook exposes once loaded.
`TStatus` extends `Record`<`string`, `unknown`>	`Record`<`string`, `unknown`>	Shape of the status flags the hook exposes.

Properties

Property	Type	Description
`data`	`TData`	Hook-specific data payload; shape is narrowed by each concrete hook via `TData`.
`errorHandling`	`HookErrorHandling`	Error state and recovery actions.
`isLoading`	`false`	Always `false` in this branch; discriminates from HookLoadingResult.
`status`	`TStatus`	Hook-specific status flags; shape is narrowed by each concrete hook via `TStatus`.

HookErrorHandling

Error state and recovery actions returned by every hook in both loading and ready states.

Remarks

errors aggregates fetch and submit errors as normalized SDKError values. Recovery is split by source: retryQueries refetches every failed data-fetching query (dependent queries re-trigger automatically when their dependencies resolve), and clearSubmitError clears the most recent submission error. Inferring which action to offer from those two methods is the supported way to discriminate fetch vs submit failures today.

Properties

Property	Type	Description
`clearSubmitError`	() => `void`	Clears the most recent submission error.
`errors`	`SDKError`[]	Aggregated fetch and submit errors as normalized SDKError values.
`retryQueries`	() => `void`	Refetches every failed data-fetching query; dependent queries re-trigger automatically when their dependencies resolve.

HookLoadingResult

Discriminated union member returned by a hook while async data is being fetched.

Remarks

Only isLoading and errorHandling are available in this branch — query errors surfaced before the hook can render its form are exposed via errorHandling.errors. Once isLoading narrows to false, the hook's ready-state shape (data, form, actions, status) becomes available.

Properties

Property	Type	Description
`errorHandling`	`HookErrorHandling`	Error state available before the form loads, e.g. for query errors surfaced during data fetching.
`isLoading`	`true`	Always `true` in this branch; narrows to `false` once the hook's ready-state shape is available.

Form hook results

Returned by form hooks — see the Hooks overview.

BaseFormHookReady

Base ready-state shape for form hooks.

Remarks

Each concrete hook narrows data, actions, and form.Fields to its own domain. status.mode matches HookSubmitResult — 'create' when no existing entity was loaded, 'update' when editing one. Document-sign hooks always surface mode: 'create', which reflects the underlying submit contract rather than a domain-level distinction. form.Fields carries the pre-bound field components, form.fieldsMetadata carries per-field presentation flags, and form.getFormSubmissionValues returns the current parsed values (or undefined if invalid).

Extended by

Type Parameters

Type Parameter	Default type	Description
`TFieldsMetadata` extends `FieldsMetadata`	`FieldsMetadata`	Shape of the per-field metadata exposed by the hook.
`TFormData` extends `FieldValues`	`FieldValues`	Shape of the form values managed by react-hook-form (the resolver input / `TFieldValues`).
`TFields` extends `object`	`Record`<`string`, `unknown`>	Shape of the pre-bound `Fields` component map.
`TFormOutputs`	`TFormData`	Shape of the values produced once the schema parses on submit (the resolver output / `TTransformedValues`). Defaults to `TFormData`, which holds whenever the form's input and parsed-output shapes coincide; pass it explicitly when a schema transform makes them diverge.

Properties

Property	Type	Description
`actions`	`Record`<`string`, `unknown`>	Hook-specific submit actions; shape is narrowed by each concrete hook.
`data`	`Record`<`string`, `unknown`>	Hook-specific data payload; shape is narrowed by each concrete hook.
`errorHandling`	`HookErrorHandling`	Error state and recovery actions.
`form`	`object`	Form bindings: pre-bound field components, per-field metadata, submission values, and react-hook-form internals.
`form.Fields`	`TFields`	-
`form.fieldsMetadata`	`TFieldsMetadata`	-
`form.getFormSubmissionValues`	() => `TFormOutputs` \| `undefined`	-
`form.hookFormInternals`	`HookFormInternals`<`TFormData`>	-
`isLoading`	`false`	Always `false` in this branch; discriminates from HookLoadingResult.
`status`	`object`	Submission state; `isPending` is `true` while a mutation is in flight, `mode` reflects whether the hook will create or update.
`status.isPending`	`boolean`	-
`status.mode`	`"create"` \| `"update"`	-

FormHookResult

FormHookResult = object

Narrowed shape accepted by the formHookResult prop on hook field components.

Remarks

Derived from BaseFormHookReady so the prop stays in sync with what form hooks return — passing the hook result directly (e.g. formHookResult={employeeDetails}) is always type-safe. Use this prop when fields from multiple hooks need to be interleaved freely instead of grouped under an SDKFormProvider.

Properties

Property	Type	Description
`errorHandling`	`Pick`<`BaseFormHookReady`[`"errorHandling"`], `"errors"`>	The error handling surface; pass to composeErrorHandler.
`form`	`Pick`<`BaseFormHookReady`[`"form"`], `"fieldsMetadata"`> & `object`	The form surface; provides field metadata and internal react-hook-form wiring.

HookFormInternals

Escape hatch exposing react-hook-form's UseFormReturn from a form hook.

Remarks

Available at form.hookFormInternals on every form hook for advanced cases not covered by the built-in API — for example, watching a field for reactive UI updates outside of the SDK fields, programmatically setting values, or triggering validation on specific fields. The built-in Fields, actions.onSubmit, and form.getFormSubmissionValues are sufficient for most use cases.

Type Parameters

Type Parameter	Default type	Description
`TFormData` extends `FieldValues`	`FieldValues`	Shape of the form values managed by react-hook-form.

Properties

Property	Type	Description
`formMethods`	`UseFormReturn`<`TFormData`>	The full react-hook-form return value; use for watching fields, setting values, or triggering validation.

HookSubmitResult

Result returned by a form hook's actions.onSubmit after a successful submission.

Remarks

mode reflects which API path ran — 'create' when no existing entity was loaded, 'update' when editing one. data is the saved entity returned by the API. A failed validation or mutation returns undefined instead, so always null-check before reading result.data.

Type Parameters

Type Parameter	Description
`T`	Type of the saved entity returned by the underlying mutation.

Properties

Property	Type	Description
`data`	`T`	The saved entity returned by the API.
`mode`	`"create"` \| `"update"`	Whether the submission created a new entity or updated an existing one.

Hook field props

Configure field behavior in Configuring form fields.

BaseFieldProps

Common presentation props accepted by every hook field component.

Properties

Property	Type	Description
`label`	`string`	Visible label rendered above the field.
`description?`	`ReactNode`	Optional helper text rendered below the field.

CheckboxHookFieldProps

Props accepted by a checkbox field surfaced through a form hook. Exposes validationMessages for custom error text alongside the shared base field attributes (label, description).

Extends

BaseFieldProps

Type Parameters

Type Parameter	Default type	Description
`TErrorCode` extends `string`	`never`	Validation error code keys mapped via `validationMessages`.

Properties

Property	Type	Description
`label`	`string`	Visible label rendered above the field.
`name`	`string`	The field name; must match the corresponding key in the form schema.
`description?`	`ReactNode`	Optional helper text rendered below the field.
`FieldComponent?`	`ComponentType`<`CheckboxProps`>	Replaces the default checkbox UI component; must accept the same props as `CheckboxProps`.
`formHookResult?`	`FormHookResult`	Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted.
`validationMessages?`	`ValidationMessages`<`TErrorCode`>	Custom error text keyed by validation error code.

DatePickerHookFieldProps

Props accepted by a date picker field surfaced through a form hook. Exposes minDate and maxDate bounds (override server-provided constraints when supplied), portalContainer for correct stacking inside modals, and validationMessages for custom error text alongside the shared base field attributes (label, description).

Extends

BaseFieldProps.Pick<DatePickerProps, "portalContainer" | "minDate" | "maxDate">

Type Parameters

Type Parameter	Default type	Description
`TErrorCode` extends `string`	`never`	Validation error code keys mapped via `validationMessages`.

Properties

Property	Type	Description
`label`	`string`	Visible label rendered above the field.
`name`	`string`	The field name; must match the corresponding key in the form schema.
`description?`	`ReactNode`	Optional helper text rendered below the field.
`FieldComponent?`	`ComponentType`<`DatePickerProps`>	Replaces the default date picker UI component; must accept the same props as `DatePickerProps`.
`formHookResult?`	`FormHookResult`	Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted.
`maxDate?`	`Date`	Maximum selectable date. Dates after this will be disabled.
`minDate?`	`Date`	Minimum selectable date. Dates before this will be disabled.
`portalContainer?`	`HTMLElement`	When used inside a modal, pass the modal backdrop ref's element so the calendar popover stacks correctly.
`validationMessages?`	`ValidationMessages`<`TErrorCode`>	Custom error text keyed by validation error code.

HookFieldProps

HookFieldProps<TProps> = Omit<TProps, "name">

Strips name from a hook field's props type for domain-specific field components that bind the form-field name internally.

Type Parameters

Type Parameter	Description
`TProps` extends `object`	Original hook field props type that includes a `name` property.

NumberInputHookFieldProps

Props accepted by a number input field surfaced through a form hook. Exposes numeric constraints (min, max), display format, placeholder text, and validationMessages for custom error text alongside the shared base field attributes (label, description).

Extends

BaseFieldProps

Type Parameters

Type Parameter	Default type	Description
`TErrorCode` extends `string`	`never`	Validation error code keys mapped via `validationMessages`.

Properties

Property	Type	Description
`label`	`string`	Visible label rendered above the field.
`name`	`string`	The field name; must match the corresponding key in the form schema.
`description?`	`ReactNode`	Optional helper text rendered below the field.
`FieldComponent?`	`ComponentType`<`NumberInputProps`>	Replaces the default number input UI component; must accept the same props as `NumberInputProps`.
`format?`	`"percent"` \| `"currency"` \| `"decimal"`	Display format for the number value (e.g. `'currency'`).
`formHookResult?`	`FormHookResult`	Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted.
`max?`	`string` \| `number`	Maximum allowed numeric value.
`min?`	`string` \| `number`	Minimum allowed numeric value.
`placeholder?`	`string`	Placeholder text displayed when the field has no value.
`validationMessages?`	`ValidationMessages`<`TErrorCode`>	Custom error text keyed by validation error code.

RadioGroupHookFieldProps

Props accepted by a radio group field surfaced through a form hook. Exposes getOptionLabel to customize how option entries are rendered as labels, and validationMessages for custom error text alongside the shared base field attributes (label, description).

Extends

BaseFieldProps

Type Parameters

Type Parameter	Default type	Description
`TErrorCode` extends `string`	`never`	Validation error code keys mapped via `validationMessages`.
`TEntry`	`unknown`	Shape of each option entry consumed by `getOptionLabel`.

Properties

Property	Type	Description
`label`	`string`	Visible label rendered above the field.
`name`	`string`	The field name; must match the corresponding key in the form schema.
`description?`	`ReactNode`	Optional helper text rendered below the field.
`FieldComponent?`	`ComponentType`<`RadioGroupProps`>	Replaces the default radio group UI component; must accept the same props as `RadioGroupProps`.
`formHookResult?`	`FormHookResult`	Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted.
`getOptionLabel?`	(`entry`: `TEntry`) => `string`	Maps a raw option entry to its display label; when omitted, options use the labels provided by the hook.
`validationMessages?`	`ValidationMessages`<`TErrorCode`>	Custom error text keyed by validation error code.

SelectHookFieldProps

Props accepted by a select field surfaced through a form hook. Exposes getOptionLabel to customize how option entries are rendered as labels, placeholder text, portalContainer for correct stacking inside modals, and validationMessages for custom error text alongside the shared base field attributes (label, description).

Extends

BaseFieldProps.Pick<SelectProps, "portalContainer">

Type Parameters

Type Parameter	Default type	Description
`TErrorCode` extends `string`	`never`	Validation error code keys mapped via `validationMessages`.
`TEntry`	`unknown`	Shape of each option entry consumed by `getOptionLabel`.

Properties

Property	Type	Description
`label`	`string`	Visible label rendered above the field.
`name`	`string`	The field name; must match the corresponding key in the form schema.
`placeholder`	`string`	Placeholder text displayed when no option is selected. Required so empty dropdowns always communicate the action — pass an empty string only when a default value is guaranteed.
`description?`	`ReactNode`	Optional helper text rendered below the field.
`FieldComponent?`	`ComponentType`<`SelectProps`>	Replaces the default select UI component; must accept the same props as `SelectProps`.
`formHookResult?`	`FormHookResult`	Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted.
`getOptionLabel?`	(`entry`: `TEntry`) => `string`	Maps a raw option entry to its display label; when omitted, options use the labels provided by the hook.
`portalContainer?`	`HTMLElement`	When used inside a modal, pass the modal backdrop ref's element so the listbox stacks correctly.
`validationMessages?`	`ValidationMessages`<`TErrorCode`>	Custom error text keyed by validation error code.

SwitchHookFieldProps

Props accepted by a toggle switch field surfaced through a form hook. Exposes validationMessages for custom error text alongside the shared base field attributes (label, description).

Extends

BaseFieldProps

Type Parameters

Type Parameter	Default type	Description
`TErrorCode` extends `string`	`never`	Validation error code keys mapped via `validationMessages`.

Properties

Property	Type	Description
`label`	`string`	Visible label rendered above the field.
`name`	`string`	The field name; must match the corresponding key in the form schema.
`description?`	`ReactNode`	Optional helper text rendered below the field.
`FieldComponent?`	`ComponentType`<`SwitchProps`>	Replaces the default toggle switch UI component; must accept the same props as `SwitchProps`.
`formHookResult?`	`FormHookResult`	Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted.
`validationMessages?`	`ValidationMessages`<`TErrorCode`>	Custom error text keyed by validation error code.

TextInputHookFieldProps

Props accepted by a text input field surfaced through a form hook. Exposes a transform function for preprocessing raw input, placeholder text, and validationMessages for custom error text alongside the shared base field attributes (label, description).

Extends

BaseFieldProps

Type Parameters

Type Parameter	Default type	Description
`TErrorCode` extends `string`	`never`	Required validation error code keys mapped via `validationMessages`.
`TOptionalErrorCode` extends `string`	`never`	Optional validation error code keys mapped via `validationMessages`.

Properties

Property	Type	Description
`label`	`string`	Visible label rendered above the field.
`name`	`string`	The field name; must match the corresponding key in the form schema.
`description?`	`ReactNode`	Optional helper text rendered below the field.
`FieldComponent?`	`ComponentType`<`TextInputProps`>	Replaces the default text input UI component; must accept the same props as `TextInputProps`.
`formHookResult?`	`FormHookResult`	Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted.
`placeholder?`	`string`	Placeholder text displayed when the field has no value.
`transform?`	(`value`: `string`) => `string`	Transforms the raw string value on every change before storing it; use for normalization such as trimming or changing case.
`validationMessages?`	`ValidationMessages`<`TErrorCode`, `TOptionalErrorCode`>	Custom error text keyed by validation error code.

Utility types

FieldMetadata

Per-field metadata published by a form hook for the matching field component.

Remarks

Carries the field's registered name plus presentation flags (required, disabled, redacted server-side value) and optional date bounds. Consumed by hook field components to render labels, inline validation, and bounded date pickers.

Extended by

FieldMetadataWithOptions

Properties

Property	Type	Description
`name`	`string`	Field name as registered with react-hook-form.
`hasRedactedValue?`	`boolean`	Whether the server returned a redacted placeholder instead of the real value.
`isDisabled?`	`boolean`	Whether the field should be rendered in a non-interactive state.
`isRequired?`	`boolean`	Whether the field must have a value for the form to submit.
`maxDate?`	`string` \| `null`	ISO date string upper bound for date picker fields. Set by hooks; consumed by DatePickerHookField.
`minDate?`	`string` \| `null`	ISO date string lower bound for date picker fields. Set by hooks; consumed by DatePickerHookField.
`placeholder?`	`string`	Placeholder text a hook supplies for the field (e.g. a masked value to display while the input is empty).

FieldMetadataWithOptions

FieldMetadata extended with the option list for select-like fields.

Remarks

Includes the label/value pairs used to render the control and, when available, the raw entries (typed via TEntry) the options were derived from so callers can read additional attributes off the originating record.

Extends

FieldMetadata

Type Parameters

Type Parameter	Default type	Description
`TEntry`	`unknown`	Shape of the underlying records that produced `options`.

Properties

Property	Type	Description
`name`	`string`	Field name as registered with react-hook-form.
`options`	`object`[]	Display options as `label`/`value` pairs used to render the select-like control.
`entries?`	readonly `TEntry`[]	Raw records the options were derived from; present when the hook supplies them for callers that need additional attributes.
`hasRedactedValue?`	`boolean`	Whether the server returned a redacted placeholder instead of the real value.
`isDisabled?`	`boolean`	Whether the field should be rendered in a non-interactive state.
`isRequired?`	`boolean`	Whether the field must have a value for the form to submit.
`maxDate?`	`string` \| `null`	ISO date string upper bound for date picker fields. Set by hooks; consumed by DatePickerHookField.
`minDate?`	`string` \| `null`	ISO date string lower bound for date picker fields. Set by hooks; consumed by DatePickerHookField.
`placeholder?`	`string`	Placeholder text a hook supplies for the field (e.g. a masked value to display while the input is empty).

FieldsMetadata

FieldsMetadata = object

Map of form-field name to FieldMetadata or FieldMetadataWithOptions.

Remarks

Exposed on every form hook as form.fieldsMetadata so field components can look up their own metadata by name.

Index Signature

[key: string]: FieldMetadata | FieldMetadataWithOptions<unknown>

ValidationMessages

ValidationMessages<TErrorCode, TOptionalErrorCode> = Record<TErrorCode, string> & Partial<Record<TOptionalErrorCode, string>>

Maps every error code a schema field can produce to a display string.

Remarks

Passed as the validationMessages prop on hook field components. The required code set (TErrorCode) must be fully covered; codes in TOptionalErrorCode may be omitted. When a message is missing, the field falls back to displaying the raw error code.

Type Parameters

Type Parameter	Default type	Description
`TErrorCode` extends `string`	-	Error codes the field is guaranteed to produce.
`TOptionalErrorCode` extends `string`	`never`	Error codes that only apply in some configurations.

Uh oh!

FilesExpand file tree

hooks.md

Latest commit

History

hooks.md

File metadata and controls

🌐 Data hooks

✍️ Form hooks

SDKFormProvider

Example

Type Parameters

SDKFormProviderProps

Form composition

composeErrorHandler()

Remarks

Example

Parameters

Returns

MixedErrorSource

QueryWithRefetch

SubmitStateForErrorHandling

Remarks

Properties

composeSubmitHandler()

Remarks

Example

Type Parameters

Parameters

Returns

ComposableFormHookResult

Properties

ComposeSubmitHandlerResult

Properties

ComposeSubmitInput

Remarks

Type Parameters

Common hook results

BaseHookReady

Remarks

Extended by

Type Parameters

Properties

HookErrorHandling

Remarks

Properties

HookLoadingResult

Remarks

Properties

Form hook results

BaseFormHookReady

Remarks

Extended by

Type Parameters

Properties

FormHookResult

Remarks

Properties

HookFormInternals

Remarks

Type Parameters

Properties

HookSubmitResult

Remarks

Type Parameters

Properties

Hook field props

BaseFieldProps

Extended by

Properties

CheckboxHookFieldProps

Extends

Type Parameters

Properties

DatePickerHookFieldProps

Extends

Type Parameters

Properties

HookFieldProps

Type Parameters