useCurrentWorkAddressForm

useCurrentWorkAddressForm(props: UseCurrentWorkAddressFormProps): UseWorkAddressFormResult

Convenience wrapper around useWorkAddressForm that auto-resolves the employee's current work address.

Remarks

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

Example

Example

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

function WorkAddressEditor({ employeeId, companyId }: { employeeId: string; companyId: string }) {
  const workAddress = useCurrentWorkAddressForm({ employeeId, companyId })

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

  const { Fields } = workAddress.form
  return (
    <form onSubmit={e => { e.preventDefault(); void workAddress.actions.onSubmit() }}>
      <Fields.Location label="Work location" />
      <button type="submit">Save</button>
    </form>
  )
}

Props

UseCurrentWorkAddressFormProps

Options for useCurrentWorkAddressForm.

Remarks

Same shape as UseWorkAddressFormProps minus workAddressUuid — the hook resolves the current work address itself.

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?	"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

UseWorkAddressFormResult

A HookLoadingResult while loading, or a UseWorkAddressFormReady once ready.

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	object	-
form.fieldsMetadata.effectiveDate	FieldMetadata	-
form.fieldsMetadata.locationUuid	FieldMetadataWithOptions<Location>	-
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.

Endpoints

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