useContractorPayForm

useContractorPayForm(props: UseContractorPayFormProps): HookLoadingResult | UseContractorPayFormReady

Headless React Hook Form hook for editing a contractor's compensation.

Remarks

Owns wageType (Fixed or Hourly) and, when Hourly, hourlyRate. Always operates in update mode — a contractor's wage type is set at creation. Every submit echoes the contractor's current type back to the API alongside the changed fields: the update endpoint's wire schema defaults an omitted type to "Individual", so a narrower payload would silently misrepresent a Business contractor.

Example

Example

import { useContractorPayForm, SDKFormProvider } from '@gusto/embedded-react-sdk'

function PayScreen({ contractorId }: { contractorId: string }) {
  const pay = useContractorPayForm({ contractorId })

  if (pay.isLoading) return null
  const { Fields } = pay.form

  return (
    <SDKFormProvider formHookResult={pay}>
      <form
        onSubmit={e => {
          e.preventDefault()
          void pay.actions.onSubmit()
        }}
      >
        <Fields.WageType label="Compensation type" />
        <Fields.HourlyRate label="Hourly rate" />
        <button type="submit" disabled={pay.status.isPending}>Save</button>
      </form>
    </SDKFormProvider>
  )
}

Props

UseContractorPayFormProps

Props for useContractorPayForm.

Property	Type	Description
contractorId	string	Contractor whose compensation is being edited.
shouldFocusError?	boolean	Auto-focus the first invalid field on submit. Set to false when using composeSubmitHandler. Defaults to true.
validationMode?	"all" | "onChange" | "onBlur" | "onSubmit" | "onTouched"	When validation runs. Passed through to react-hook-form. Defaults to 'onSubmit'.

Returns

HookLoadingResult | UseContractorPayFormReady

A loading-state result while data loads, or a UseContractorPayFormReady once ready.

UseContractorPayFormResult

UseContractorPayFormResult = HookLoadingResult | UseContractorPayFormReady

Return type of useContractorPayForm — a discriminated union on isLoading.

---

UseContractorPayFormReady

Ready-state return value of useContractorPayForm.

Property	Type	Description
actions	object	Submit the form. Returns the updated contractor on success or undefined on validation/mutation failure.
actions.onSubmit	() => Promise<HookSubmitResult<Contractor> | undefined>	-
data	object	The full contractor entity, loaded from the API.
data.contractor	Contractor	-
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	ContractorPayFormFields	-
form.fieldsMetadata	ContractorPayFieldsMetadata	-
form.getFormSubmissionValues	() => ContractorPayFormData | undefined	-
form.hookFormInternals	HookFormInternals<ContractorPayFormData>	-
isLoading	false	Always false in this branch; discriminates from HookLoadingResult.
status	object	isPending reflects the in-flight update mutation; mode is always 'update'. isHourly reflects the currently selected wage type so a composing component can decide whether to render the hourly-rate field.
status.isHourly	boolean	-
status.isPending	boolean	-
status.mode	"update"	-

Fields

ContractorPayFormFields

Field components exposed by useContractorPayForm on form.Fields.

Property	Type	Description
HourlyRate	ComponentType<HourlyRateFieldProps>	Bound to hourlyRate. Required and rendered only when wageType is Hourly.
WageType	ComponentType<WageTypeFieldProps>	Bound to wageType. Selects whether the contractor is paid Fixed or Hourly.

---

HourlyRate

Bound to hourlyRate. Required and rendered only when wageType is Hourly.

<form.Fields.HourlyRate
  label="Hourly rate"
  validationMessages={{ REQUIRED: '…', MAX_HOURLY_RATE: '…' }}
/>

ContractorPayHourlyRateFieldProps

HookFieldProps<NumberInputHookFieldProps<ContractorPayRequiredValidation | ContractorPayMaxHourlyRateValidation>>

Props accepted by useContractorPayForm's Fields.HourlyRate component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<NumberInputProps>	Replaces the default number input UI component; must accept the same props as NumberInputProps.
validationMessages?	ValidationMessages<ContractorPayRequiredValidation | ContractorPayMaxHourlyRateValidation>	Custom error text keyed by validation error code.

Also accepts description, format, formHookResult, max, min, placeholder from NumberInputHookFieldProps.

---

WageType

Bound to wageType. Selects whether the contractor is paid Fixed or Hourly.

<form.Fields.WageType label="Wage type" />

ContractorPayWageTypeFieldProps

HookFieldProps<RadioGroupHookFieldProps<never, ContractorPayFormData["wageType"]>>

Props accepted by useContractorPayForm's Fields.WageType component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<RadioGroupProps>	Replaces the default radio group UI component; must accept the same props as RadioGroupProps.
getOptionLabel?	(entry: ContractorPayFormData["wageType"]) => string	Maps a raw option entry to its display label; when omitted, options use the labels provided by the hook.

Also accepts description, formHookResult from RadioGroupHookFieldProps.

Utility types

ContractorPayErrorCode

ContractorPayErrorCode = "REQUIRED" | "MAX_HOURLY_RATE"

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

---

ContractorPayErrorCodes

const ContractorPayErrorCodes: object

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

Type Declaration

Name	Type
MAX_HOURLY_RATE	"MAX_HOURLY_RATE"
REQUIRED	"REQUIRED"

---

ContractorPayFieldsMetadata

Field	Type
hourlyRate	FieldMetadata
wageType	FieldMetadataWithOptions<"Fixed" | "Hourly">

Per-field metadata exposed on form.fieldsMetadata for useContractorPayForm.

---

ContractorPayFormData

Shape of the values managed by the contractor pay form.

Properties

Property	Type
hourlyRate	number
wageType	"Fixed" | "Hourly"

---

ContractorPayFormField

ContractorPayFormField = "hourlyRate" | "wageType"

Field names accepted by the contractor pay form.

---

ContractorPayMaxHourlyRateValidation

ContractorPayMaxHourlyRateValidation = "MAX_HOURLY_RATE"

Validation code for an hourly rate above the server's maximum cap.

---

ContractorPayRequiredValidation

ContractorPayRequiredValidation = "REQUIRED"

Validation code for a required contractor pay field.

---

ContractorPayWageType

const ContractorPayWageType: object = ApiWageType

Contractor wage type enum (Fixed / Hourly) re-exported from the API model.

Type Declaration

Name	Type
Fixed	"Fixed"
Hourly	"Hourly"

---

Endpoints

Method	Path
GET	/v1/contractors/:contractorUuid
PUT	/v1/contractors/:contractorUuid