Hooks

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

• UseDeductionFormReady
• UseChildSupportGarnishmentFormReady
• UseCompensationFormReady
• UseJobFormReady
• UseEmployeeDetailsFormReady
• UseContractorDetailsFormReady
• UseContractorBankAccountFormReady
• UseContractorPaymentMethodFormReady
• UseWorkAddressFormReady
• UseHomeAddressFormReady
• UseContractorAddressFormReady
• UseBankFormReady
• UsePaymentMethodFormReady
• UseSplitPaymentsFormReady
• UseEmployeeStateTaxesFormReady
• UseFederalTaxesFormReady
• UseSignEmployeeFormReady
• UsePayScheduleFormReady
• UseSignCompanyFormReady
• UseContractorSignatureFormReady

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.

Extended by

• TextInputHookFieldProps
• SelectHookFieldProps
• CheckboxHookFieldProps
• NumberInputHookFieldProps
• DatePickerHookFieldProps
• RadioGroupHookFieldProps
• SwitchHookFieldProps

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.