useCurrentHomeAddressForm

useCurrentHomeAddressForm(props: UseCurrentHomeAddressFormProps): UseHomeAddressFormResult

Convenience wrapper around useHomeAddressForm that auto-resolves the employee's current home address.

Remarks

Lists the employee's home addresses and selects the active one (or the first when none are active) as the row to edit. When the employee has no home address on file the hook operates in create mode. The returned shape is identical to useHomeAddressForm, so the same Fields, actions.onSubmit, and errorHandling apply.

Example

Example

import { useCurrentHomeAddressForm } from '@gusto/embedded-react-sdk'

function HomeAddressEditor({ employeeId }: { employeeId: string }) {
  const homeAddress = useCurrentHomeAddressForm({ employeeId })

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

  const { Fields } = homeAddress.form
  return (
    <form onSubmit={e => { e.preventDefault(); void homeAddress.actions.onSubmit() }}>
      <Fields.Street1 label="Street" />
      <Fields.City label="City" />
      <Fields.State label="State" />
      <Fields.Zip label="ZIP" />
      <button type="submit">Save</button>
    </form>
  )
}

Props

UseCurrentHomeAddressFormProps

Options for useCurrentHomeAddressForm.

Remarks

Same shape as UseHomeAddressFormProps minus homeAddressUuid — the hook resolves the current home address itself.

Property	Type	Description
employeeId	string	UUID of the employee whose home address is being created or edited.
defaultValues?	Partial<HomeAddressFormData>	Pre-fill form values. Server data takes precedence on update.
initialAddress?	EmployeeAddress	Pre-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?	HomeAddressOptionalFieldsToRequire	Override fields that are optional on a given mode to be required. See HomeAddressOptionalFieldsToRequire.
shouldFocusError?	boolean	Auto-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?	"onChange" | "onBlur" | "onSubmit" | "onTouched" | "all"	Passed through to react-hook-form. Defaults to 'onSubmit'.
withEffectiveDateField?	boolean	When true, renders Fields.EffectiveDate; otherwise it is undefined. Defaults to true.

Returns

UseHomeAddressFormResult

A HookLoadingResult while loading, or a UseHomeAddressFormReady once ready.

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.

Property	Type	Description
actions	object	Available actions.
actions.onSubmit	(options?: HomeAddressSubmitOptions) => Promise<HookSubmitResult<EmployeeAddress> | undefined>	-
data	object	Static entity data resolved from the API.
data.homeAddress	EmployeeAddress | null	The address row loaded for update; null in create mode.
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	HomeAddressFormFields	-
form.fieldsMetadata	object	-
form.fieldsMetadata.city	FieldMetadata	-
form.fieldsMetadata.courtesyWithholding	FieldMetadata	-
form.fieldsMetadata.effectiveDate	FieldMetadata	-
form.fieldsMetadata.state	FieldMetadataWithOptions<"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">	-
form.fieldsMetadata.street1	FieldMetadata	-
form.fieldsMetadata.street2	FieldMetadata	-
form.fieldsMetadata.zip	FieldMetadata	-
form.getFormSubmissionValues	() => HomeAddressFormData | undefined	-
form.hookFormInternals	HookFormInternals<HomeAddressFormData>	-
isLoading	false	Always false in this branch; discriminates from HookLoadingResult.
status	object	Reactive status flags.
status.isPending	boolean	-
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.

Property	Type	Description
City	ComponentType<CityFieldProps>	Bound to city. City text input. Always available.
CourtesyWithholding	ComponentType<CourtesyWithholdingFieldProps>	Bound to courtesyWithholding. Courtesy withholding checkbox. Always available.
State	ComponentType<StateFieldProps>	Bound to state. State selector. Always available.
Street1	ComponentType<Street1FieldProps>	Bound to street1. Street address line 1 text input. Always available.
Street2	ComponentType<Street2FieldProps>	Bound to street2. Street address line 2 text input. Always available.
Zip	ComponentType<ZipFieldProps>	Bound to zip. ZIP code text input. Always available.
EffectiveDate	ComponentType<EffectiveDateFieldProps> | undefined	Bound 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.

Property	Type	Description
label	string	Visible 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.

Property	Type	Description
label	string	Visible 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.

Property	Type	Description
label	string	Visible 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.

Property	Type	Description
label	string	Visible label rendered above the field.
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.
FieldComponent?	ComponentType<SelectProps>	Replaces the default select UI component; must accept the same props as SelectProps.
getOptionLabel?	(entry: string) => string	Maps 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.

Property	Type	Description
label	string	Visible 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.

Property	Type	Description
label	string	Visible 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.

Property	Type	Description
label	string	Visible 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.

Endpoints

Method	Path
GET	/v1/employees/:employeeId/home_addresses
POST	/v1/employees/:employeeId/home_addresses
GET	/v1/home_addresses/:homeAddressUuid
PUT	/v1/home_addresses/:homeAddressUuid