useWorkAddressForm

useWorkAddressForm(props: UseWorkAddressFormProps): HookLoadingResult | UseWorkAddressFormReady

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

Remarks

When workAddressUuid is supplied the hook loads that address and issues a PUT on submit; when omitted it operates in create mode and issues a POST. The hook requires companyId to fetch the company's location list — it stays in loading state until companyId is known.

Example

Example

import {
  useWorkAddressForm,
  SDKFormProvider,
  type UseWorkAddressFormReady,
} from '@gusto/embedded-react-sdk'

function WorkAddressPage({ companyId, employeeId }: { companyId: string; employeeId: string }) {
  const workAddress = useWorkAddressForm({ companyId, employeeId })

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

  return <WorkAddressReady workAddress={workAddress} />
}

function WorkAddressReady({ workAddress }: { workAddress: UseWorkAddressFormReady }) {
  const { Fields } = workAddress.form

  return (
    <SDKFormProvider formHookResult={workAddress}>
      <form onSubmit={e => { e.preventDefault(); void workAddress.actions.onSubmit() }}>
        <Fields.Location label="Work address" />
        {Fields.EffectiveDate && <Fields.EffectiveDate label="Effective date" />}
        <button type="submit" disabled={workAddress.status.isPending}>Save</button>
      </form>
    </SDKFormProvider>
  )
}

Props

UseWorkAddressFormProps

Configuration options for useWorkAddressForm.

Remarks

Presence or absence of workAddressUuid selects the API verb — see the workAddressUuid field description. companyId is required to fetch the location list; pass it when it is known.

Property	Type	Description
employeeId	string	UUID of the employee whose work address is being created or edited.
companyId?	string	Company UUID for locations; omit or leave unset while resolving from the employee record.
defaultValues?	Partial<WorkAddressFormData>	Pre-fill form values. Server data takes precedence on update.
initialAddress?	EmployeeWorkAddress	Pre-loaded address matching workAddressUuid. 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?	WorkAddressOptionalFieldsToRequire	Override fields that are optional on a given mode to be required. See WorkAddressOptionalFieldsToRequire.
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?	"all" | "onChange" | "onBlur" | "onSubmit" | "onTouched"	Passed through to react-hook-form. Defaults to 'onSubmit'.
withEffectiveDateField?	boolean	When true, renders Fields.EffectiveDate; otherwise it is undefined. Defaults to true.
workAddressUuid?	string	When set, loads that work address via GET /v1/work_addresses/{work_address_uuid} and updates it (PUT). When omitted, the form is in create mode (POST).

Returns

HookLoadingResult | UseWorkAddressFormReady

A HookLoadingResult while loading, or a UseWorkAddressFormReady once ready.

UseWorkAddressFormResult

UseWorkAddressFormResult = HookLoadingResult | UseWorkAddressFormReady

Discriminated union returned by useWorkAddressForm.

---

UseWorkAddressFormReady

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

Remarks

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

Property	Type	Description
actions	object	Available actions.
actions.onSubmit	(callbacks?: WorkAddressSubmitCallbacks, options?: WorkAddressSubmitOptions) => Promise<HookSubmitResult<EmployeeWorkAddress> | undefined>	-
data	object	Static entity data resolved from the API.
data.companyLocations	Location[] | undefined	Company locations available for selection; undefined until the locations query resolves.
data.workAddress	EmployeeWorkAddress | 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	WorkAddressFormFields	-
form.fieldsMetadata	WorkAddressFieldsMetadata	-
form.getFormSubmissionValues	() => WorkAddressFormData | undefined	-
form.hookFormInternals	HookFormInternals<WorkAddressFormData>	-
isLoading	false	Always false in this branch; discriminates from HookLoadingResult.
status	object	Reactive status flags.
status.isPending	boolean	-
status.mode	"create" | "update"	-

Fields

WorkAddressFormFields

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

Remarks

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

Property	Type	Description
Location	ComponentType<LocationFieldProps>	Bound to locationUuid. Location selector. Always available.
EffectiveDate	ComponentType<EffectiveDateFieldProps> | undefined	Bound to effectiveDate. Effective-date picker. Only available when withEffectiveDateField is true.

---

EffectiveDate

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

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

EffectiveDateFieldProps

HookFieldProps<DatePickerHookFieldProps<WorkAddressRequiredValidation>>

Props accepted by useWorkAddressForm'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<WorkAddressRequiredValidation>	Custom error text keyed by validation error code.

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

---

Location

Bound to locationUuid. Location selector. Always available.

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

LocationFieldProps

HookFieldProps<SelectHookFieldProps<WorkAddressRequiredValidation, Location>>

Props accepted by useWorkAddressForm's Fields.Location 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: Location) => string	Maps a raw option entry to its display label; when omitted, options use the labels provided by the hook.
validationMessages?	ValidationMessages<WorkAddressRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult, portalContainer from SelectHookFieldProps.

Validations

WorkAddressRequiredValidation

WorkAddressRequiredValidation = "REQUIRED"

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

Remarks

Used as the validationMessages key for the location and effective date fields. See WorkAddressErrorCodes.

Utility types

WorkAddressErrorCode

WorkAddressErrorCode = "REQUIRED"

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

---

WorkAddressErrorCodes

const WorkAddressErrorCodes: object

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

Type Declaration

Name	Type
REQUIRED	"REQUIRED"

---

WorkAddressField

WorkAddressField = "effectiveDate" | "locationUuid"

Field names accepted by the work address form.

---

WorkAddressFieldsMetadata

Field	Type
effectiveDate	FieldMetadata
locationUuid	FieldMetadataWithOptions<Location>

Type of form.fieldsMetadata returned by useWorkAddressForm.

---

WorkAddressFormData

Shape of the values managed by the work address form.

Properties

Property	Type
effectiveDate	string
locationUuid	string

---

WorkAddressOptionalFieldsToRequire

WorkAddressOptionalFieldsToRequire = OptionalFieldsToRequire<typeof requiredFieldsConfig>

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

---

WorkAddressSubmitCallbacks

Optional callbacks passed to onSubmit.

Remarks

Only the callback matching the submit mode fires — onWorkAddressCreated on create, onWorkAddressUpdated on update.

Properties

Property	Type	Description
onWorkAddressCreated?	(workAddress: EmployeeWorkAddress) => void	Fired after a new work address is successfully created.
onWorkAddressUpdated?	(workAddress: EmployeeWorkAddress) => void	Fired after an existing work address is successfully updated.

---

WorkAddressSubmitOptions

Optional overrides passed to onSubmit.

Properties

Property	Type	Description
effectiveDate?	string	Override the effective date submitted with the address.
employeeId?	string	Override the employee identifier supplied to the hook (e.g. after creating a new employee in the same flow).

Endpoints

Method	Path
GET	/v1/companies/:companyId/locations
POST	/v1/employees/:employeeId/work_addresses
GET	/v1/work_addresses/:workAddressUuid
PUT	/v1/work_addresses/:workAddressUuid