Skip to main content

useContractorAddressForm

useContractorAddressForm(props: UseContractorAddressFormProps): HookLoadingResult | UseContractorAddressFormReady

Form hook for editing a contractor's address.

Remarks​

A contractor always has exactly one address (created with the contractor), so this hook operates only in update mode and issues a PUT on submit. The same address is labelled a "home" address for Individual contractors and a "business" address for Business contractors; the hook exposes contractorType so the consuming component can choose the appropriate copy.

Example​

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

function ContractorAddressPage({ contractorId }: { contractorId: string }) {
  const contractorAddress = useContractorAddressForm({ contractorId })

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

  return <ContractorAddressReady contractorAddress={contractorAddress} />
}

function ContractorAddressReady({
  contractorAddress,
}: {
  contractorAddress: UseContractorAddressFormReady
}) {
  const { Fields } = contractorAddress.form

  return (
    <SDKFormProvider formHookResult={contractorAddress}>
      <form onSubmit={e => { e.preventDefault(); void contractorAddress.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" />
        <button type="submit" disabled={contractorAddress.status.isPending}>Save</button>
      </form>
    </SDKFormProvider>
  )
}

Props​

UseContractorAddressFormProps​

Configuration options for useContractorAddressForm.

PropertyTypeDescription
contractorIdstringUUID of the contractor whose address is being edited.
defaultValues?Partial<ContractorAddressFormData>Pre-fill form values. Server data takes precedence.
optionalFieldsToRequire?ContractorAddressOptionalFieldsToRequireOverride fields that are optional by default to be required. See ContractorAddressOptionalFieldsToRequire.
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'.

Returns​

HookLoadingResult | UseContractorAddressFormReady

A HookLoadingResult while loading, or a UseContractorAddressFormReady once ready.

UseContractorAddressFormResult​

UseContractorAddressFormResult = HookLoadingResult | UseContractorAddressFormReady

Discriminated union returned by useContractorAddressForm.

UseContractorAddressFormReady​

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

Remarks

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

PropertyTypeDescription
actionsobjectAvailable actions.
actions.onSubmit(options?: ContractorAddressSubmitOptions) => Promise<HookSubmitResult<ContractorAddress> | undefined>-
dataobjectStatic entity data resolved from the API.
data.contractorContractorThe full contractor entity loaded alongside the address.
data.contractorAddressContractorAddressThe contractor address row loaded for update.
data.contractorTypeContractorType | undefinedThe contractor's type — drives whether the address is labelled "home" (Individual) or "business" (Business).
errorHandlingHookErrorHandlingError state and recovery actions.
formobjectForm bindings: pre-bound field components, per-field metadata, submission values, and react-hook-form internals.
form.FieldsContractorAddressFormFields-
form.fieldsMetadataContractorAddressFieldsMetadata-
form.getFormSubmissionValues() => ContractorAddressFormData | undefined-
form.hookFormInternalsHookFormInternals<ContractorAddressFormData>-
isLoadingfalseAlways false in this branch; discriminates from HookLoadingResult.
statusobjectReactive status flags.
status.isPendingboolean-
status.mode"update"-

Fields​

ContractorAddressFormFields​

Field components exposed by useContractorAddressForm on form.Fields.

PropertyTypeDescription
CityComponentType<CityFieldProps>Bound to city. Text input for the city. Required.
StateComponentType<StateFieldProps>Bound to state. Select whose options are the standard two-letter US state abbreviations. Supply getOptionLabel to localize the option labels. Required.
Street1ComponentType<Street1FieldProps>Bound to street1. Text input for the first street address line. Required.
Street2ComponentType<Street2FieldProps>Bound to street2. Text input for the second street address line. Optional.
ZipComponentType<ZipFieldProps>Bound to zip. Text input for the ZIP code. Required; also validates ZIP format and emits INVALID_ZIP when the value does not match.

City​

Bound to city. Text input for the city. Required.

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

ContractorAddressCityFieldProps​

HookFieldProps<TextInputHookFieldProps<ContractorAddressRequiredValidation>>

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

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

State​

Bound to state. Select whose options are the standard two-letter US state abbreviations. Supply getOptionLabel to localize the option labels. Required.

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

ContractorAddressStateFieldProps​

HookFieldProps<SelectHookFieldProps<ContractorAddressRequiredValidation, string>>

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

Also accepts description, formHookResult, portalContainer from SelectHookFieldProps.

Street1​

Bound to street1. Text input for the first street address line. Required.

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

ContractorAddressStreet1FieldProps​

HookFieldProps<TextInputHookFieldProps<ContractorAddressRequiredValidation>>

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

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

Street2​

Bound to street2. Text input for the second street address line. Optional.

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

ContractorAddressStreet2FieldProps​

HookFieldProps<TextInputHookFieldProps<ContractorAddressRequiredValidation>>

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

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

Zip​

Bound to zip. Text input for the ZIP code. Required; also validates ZIP format and emits INVALID_ZIP when the value does not match.

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

ContractorAddressZipFieldProps​

HookFieldProps<TextInputHookFieldProps<ContractorAddressZipValidation>>

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

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

Validations​

ContractorAddressRequiredValidation​

ContractorAddressRequiredValidation = "REQUIRED"

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

Remarks​

Used as the validationMessages key for the street, city, and state fields. See ContractorAddressErrorCodes.

ContractorAddressZipValidation​

ContractorAddressZipValidation = "REQUIRED" | "INVALID_ZIP"

Validation error codes emitted by the zip field of useContractorAddressForm.

Remarks​

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

Utility types​

ContractorAddressErrorCode​

ContractorAddressErrorCode = "REQUIRED" | "INVALID_ZIP"

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

ContractorAddressErrorCodes​

const ContractorAddressErrorCodes: object

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

Type Declaration​

NameType
INVALID_ZIP"INVALID_ZIP"
REQUIRED"REQUIRED"

ContractorAddressField​

ContractorAddressField = "street1" | "city" | "state" | "zip" | "street2"

Field names accepted by the contractor address form.

ContractorAddressFieldsMetadata​

FieldType
cityFieldMetadata
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 useContractorAddressForm.

ContractorAddressFormData​

Shape of the values managed by the contractor address form.

Properties​

PropertyType
citystring
statestring
street1string
street2string
zipstring

ContractorAddressOptionalFieldsToRequire​

ContractorAddressOptionalFieldsToRequire = OptionalFieldsToRequire<typeof requiredFieldsConfig>

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

ContractorAddressSubmitOptions​

Optional overrides passed to onSubmit.

Properties​

PropertyTypeDescription
contractorId?stringOverride the contractor identifier supplied to the hook.

Endpoints​

MethodPath
GET/v1/contractors/:contractorUuid
GET/v1/contractors/:contractorUuid/address
PUT/v1/contractors/:contractorUuid/address