Skip to main content

useHomeAddressForm

useHomeAddressForm(props: UseHomeAddressFormProps): HookLoadingResult | UseHomeAddressFormReady

Form hook for creating or editing an employee's home address.

Remarks​

When homeAddressUuid is supplied the hook loads that address and issues a PUT on submit; when omitted it operates in create mode and issues a POST. Pass initialAddress to skip the fetch when the parent already holds the row.

Example​

Example
import {
  useHomeAddressForm,
  SDKFormProvider,
  type UseHomeAddressFormReady,
} from '@gusto/embedded-react-sdk'

function HomeAddressPage({ employeeId }: { employeeId: string }) {
  const homeAddress = useHomeAddressForm({ employeeId })

  if (homeAddress.isLoading) return <div>Loading...</div>

  return <HomeAddressReady homeAddress={homeAddress} />
}

function HomeAddressReady({ homeAddress }: { homeAddress: UseHomeAddressFormReady }) {
  const { Fields } = homeAddress.form

  return (
    <SDKFormProvider formHookResult={homeAddress}>
      <form onSubmit={e => { e.preventDefault(); void homeAddress.actions.onSubmit() }}>
        <Fields.Street1 label="Street address" />
        <Fields.Street2 label="Apt, suite, etc. (optional)" />
        <Fields.City label="City" />
        <Fields.State label="State" />
        <Fields.Zip label="ZIP code" />
        <Fields.CourtesyWithholding label="Courtesy withholding" />
        {Fields.EffectiveDate && <Fields.EffectiveDate label="Effective date" />}
        <button type="submit" disabled={homeAddress.status.isPending}>Save</button>
      </form>
    </SDKFormProvider>
  )
}

Props​

UseHomeAddressFormProps​

Configuration options for useHomeAddressForm.

Remarks

Presence or absence of homeAddressUuid selects the API verb — see the homeAddressUuid field description.

PropertyTypeDescription
employeeIdstringUUID of the employee whose home address is being created or edited.
defaultValues?Partial<HomeAddressFormData>Pre-fill form values. Server data takes precedence on update.
homeAddressUuid?stringWhen set, loads that home address via GET /v1/home_addresses/{uuid} and updates it (PUT). When omitted, the form is in create mode (POST).
initialAddress?EmployeeAddressPre-loaded address matching homeAddressUuid. When supplied, the form uses it directly instead of issuing a GET — useful when the parent already has the row from a list query.
optionalFieldsToRequire?HomeAddressOptionalFieldsToRequireOverride fields that are optional on a given mode to be required. See HomeAddressOptionalFieldsToRequire.
shouldFocusError?booleanAuto-focus the first invalid field on submit. Set to false when using composeSubmitHandler so submit-time focus is coordinated across multiple forms. Defaults to true.
validationMode?"all" | "onChange" | "onBlur" | "onSubmit" | "onTouched"Passed through to react-hook-form. Defaults to 'onSubmit'.
withEffectiveDateField?booleanWhen true, renders Fields.EffectiveDate; otherwise it is undefined. Defaults to true.

Returns​

HookLoadingResult | UseHomeAddressFormReady

A HookLoadingResult while loading, or a UseHomeAddressFormReady once ready.

UseHomeAddressFormResult​

UseHomeAddressFormResult = HookLoadingResult | UseHomeAddressFormReady

Discriminated union returned by useHomeAddressForm.

UseHomeAddressFormReady​

Ready-state shape returned by useHomeAddressForm once data has loaded.

Remarks

Discriminated by isLoading: false. Extends BaseFormHookReady with the home-address-specific data, status, actions, and form.Fields shape.

PropertyTypeDescription
actionsobjectAvailable actions.
actions.onSubmit(options?: HomeAddressSubmitOptions) => Promise<HookSubmitResult<EmployeeAddress> | undefined>-
dataobjectStatic entity data resolved from the API.
data.homeAddressEmployeeAddress | nullThe address row loaded for update; null in create mode.
errorHandlingHookErrorHandlingError state and recovery actions.
formobjectForm bindings: pre-bound field components, per-field metadata, submission values, and react-hook-form internals.
form.FieldsHomeAddressFormFields-
form.fieldsMetadataHomeAddressFieldsMetadata-
form.getFormSubmissionValues() => HomeAddressFormData | undefined-
form.hookFormInternalsHookFormInternals<HomeAddressFormData>-
isLoadingfalseAlways false in this branch; discriminates from HookLoadingResult.
statusobjectReactive status flags.
status.isPendingboolean-
status.mode"create" | "update"-

Fields​

HomeAddressFormFields​

Pre-bound field components exposed on useHomeAddressForm().form.Fields.

Remarks

EffectiveDate is undefined when withEffectiveDateField is false. Always null-check it before rendering.

PropertyTypeDescription
CityComponentType<CityFieldProps>Bound to city. City text input. Always available.
CourtesyWithholdingComponentType<CourtesyWithholdingFieldProps>Bound to courtesyWithholding. Courtesy withholding checkbox. Always available.
StateComponentType<StateFieldProps>Bound to state. State selector. Always available.
Street1ComponentType<Street1FieldProps>Bound to street1. Street address line 1 text input. Always available.
Street2ComponentType<Street2FieldProps>Bound to street2. Street address line 2 text input. Always available.
ZipComponentType<ZipFieldProps>Bound to zip. ZIP code text input. Always available.
EffectiveDateComponentType<EffectiveDateFieldProps> | undefinedBound to effectiveDate. Effective-date picker. Only available when withEffectiveDateField is true.

City​

Bound to city. City text input. Always available.

<form.Fields.City
  label="City"
  validationMessages={{ REQUIRED: '…' }}
/>

CityFieldProps​

HookFieldProps<TextInputHookFieldProps<HomeAddressRequiredValidation>>

Props accepted by useHomeAddressForm's Fields.City component.

PropertyTypeDescription
labelstringVisible label rendered above the field.
FieldComponent?ComponentType<TextInputProps>Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?ValidationMessages<HomeAddressRequiredValidation>Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

CourtesyWithholding​

Bound to courtesyWithholding. Courtesy withholding checkbox. Always available.

<form.Fields.CourtesyWithholding
  label="Courtesy withholding"
  validationMessages={{ REQUIRED: '…' }}
/>

CourtesyWithholdingFieldProps​

HookFieldProps<CheckboxHookFieldProps<HomeAddressRequiredValidation>>

Props accepted by useHomeAddressForm's Fields.CourtesyWithholding component.

PropertyTypeDescription
labelstringVisible label rendered above the field.
FieldComponent?ComponentType<CheckboxProps>Replaces the default checkbox UI component; must accept the same props as CheckboxProps.
validationMessages?ValidationMessages<HomeAddressRequiredValidation>Custom error text keyed by validation error code.

Also accepts description, formHookResult from CheckboxHookFieldProps.

EffectiveDate​

Bound to effectiveDate. Effective-date picker. Only available when withEffectiveDateField is true.

{form.Fields.EffectiveDate && (
  <form.Fields.EffectiveDate
    label="Effective date"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

HomeAddressEffectiveDateFieldProps​

HookFieldProps<DatePickerHookFieldProps<HomeAddressRequiredValidation>>

Props accepted by useHomeAddressForm's Fields.EffectiveDate component.

PropertyTypeDescription
labelstringVisible label rendered above the field.
FieldComponent?ComponentType<DatePickerProps>Replaces the default date picker UI component; must accept the same props as DatePickerProps.
validationMessages?ValidationMessages<HomeAddressRequiredValidation>Custom error text keyed by validation error code.

Also accepts description, formHookResult, maxDate, minDate, portalContainer from DatePickerHookFieldProps.

State​

Bound to state. State selector. Always available.

<form.Fields.State
  label="State"
  validationMessages={{ REQUIRED: '…' }}
/>

StateFieldProps​

HookFieldProps<SelectHookFieldProps<HomeAddressRequiredValidation, string>>

Props accepted by useHomeAddressForm's Fields.State component.

PropertyTypeDescription
labelstringVisible label rendered above the field.
placeholderstringPlaceholder 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.
FieldComponent?ComponentType<SelectProps>Replaces the default select UI component; must accept the same props as SelectProps.
getOptionLabel?(entry: string) => stringMaps a raw option entry to its display label; when omitted, options use the labels provided by the hook.
validationMessages?ValidationMessages<HomeAddressRequiredValidation>Custom error text keyed by validation error code.

Also accepts description, formHookResult, portalContainer from SelectHookFieldProps.

Street1​

Bound to street1. Street address line 1 text input. Always available.

<form.Fields.Street1
  label="Street1"
  validationMessages={{ REQUIRED: '…' }}
/>

Street1FieldProps​

HookFieldProps<TextInputHookFieldProps<HomeAddressRequiredValidation>>

Props accepted by useHomeAddressForm's Fields.Street1 component.

PropertyTypeDescription
labelstringVisible label rendered above the field.
FieldComponent?ComponentType<TextInputProps>Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?ValidationMessages<HomeAddressRequiredValidation>Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

Street2​

Bound to street2. Street address line 2 text input. Always available.

<form.Fields.Street2
  label="Street2"
  validationMessages={{ REQUIRED: '…' }}
/>

Street2FieldProps​

HookFieldProps<TextInputHookFieldProps<HomeAddressRequiredValidation>>

Props accepted by useHomeAddressForm's Fields.Street2 component.

PropertyTypeDescription
labelstringVisible label rendered above the field.
FieldComponent?ComponentType<TextInputProps>Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?ValidationMessages<HomeAddressRequiredValidation>Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

Zip​

Bound to zip. ZIP code text input. Always available.

<form.Fields.Zip
  label="Zip"
  validationMessages={{ REQUIRED: '…', INVALID_ZIP: '…' }}
/>

ZipFieldProps​

HookFieldProps<TextInputHookFieldProps<ZipValidation>>

Props accepted by useHomeAddressForm's Fields.Zip component.

PropertyTypeDescription
labelstringVisible label rendered above the field.
FieldComponent?ComponentType<TextInputProps>Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?ValidationMessages<ZipValidation>Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

Validations​

HomeAddressRequiredValidation​

HomeAddressRequiredValidation = "REQUIRED"

The required-field error code produced by useHomeAddressForm fields that only emit REQUIRED.

Remarks​

Used as the validationMessages key for the street, city, state, courtesy withholding, and effective date fields. See HomeAddressErrorCodes.

ZipValidation​

ZipValidation = "REQUIRED" | "INVALID_ZIP"

Validation error codes emitted by the zip field of useHomeAddressForm.

Remarks​

Use these as keys in validationMessages on Fields.Zip. See HomeAddressErrorCodes.

Utility types​

HomeAddressErrorCode​

HomeAddressErrorCode = "REQUIRED" | "INVALID_ZIP"

Union of validation error code strings emitted by the home address form schema.

HomeAddressErrorCodes​

const HomeAddressErrorCodes: object

Validation error codes emitted by the home address form schema. Map these codes to localized copy in validationMessages when composing the hook.

Type Declaration​

NameType
INVALID_ZIP"INVALID_ZIP"
REQUIRED"REQUIRED"

HomeAddressField​

HomeAddressField = "street1" | "city" | "state" | "zip" | "street2" | "effectiveDate" | "courtesyWithholding"

Field names accepted by the home address form.

HomeAddressFieldsMetadata​

FieldType
cityFieldMetadata
courtesyWithholdingFieldMetadata
effectiveDateFieldMetadata
stateFieldMetadataWithOptions<"AL" | "AK" | "AZ" | "AR" | "CA" | "CO" | "CT" | "DE" | "DC" | "FL" | "GA" | "HI" | "ID" | "IL" | "IN" | "IA" | "KS" | "KY" | "LA" | "ME" | "MD" | "MA" | "MI" | "MN" | "MS" | "MO" | "MT" | "NE" | "NV" | "NH" | "NJ" | "NM" | "NY" | "NC" | "ND" | "OH" | "OK" | "OR" | "PA" | "RI" | "SC" | "SD" | "TN" | "TX" | "UT" | "VT" | "VA" | "WA" | "WV" | "WI" | "WY">
street1FieldMetadata
street2FieldMetadata
zipFieldMetadata

Type of form.fieldsMetadata returned by useHomeAddressForm.

HomeAddressFormData​

Shape of the values managed by the home address form.

Properties​

PropertyType
citystring
courtesyWithholdingboolean
effectiveDatestring
statestring
street1string
street2string
zipstring

HomeAddressOptionalFieldsToRequire​

HomeAddressOptionalFieldsToRequire = OptionalFieldsToRequire<typeof requiredFieldsConfig>

Keys of optional home address fields that can be promoted to required via the hook's optionalFieldsToRequire option.

HomeAddressSubmitOptions​

Optional overrides passed to onSubmit.

Properties​

PropertyTypeDescription
effectiveDate?stringOverride the effective date submitted with the address. When omitted on update without an effective-date field, the row's effectiveDate from the fetched address is used.
employeeId?stringOverride the employee identifier supplied to the hook (e.g. after creating a new employee in the same flow).

Endpoints​

MethodPath
POST/v1/employees/:employeeId/home_addresses
GET/v1/home_addresses/:homeAddressUuid
PUT/v1/home_addresses/:homeAddressUuid