useChildSupportGarnishmentForm

useChildSupportGarnishmentForm(input: UseChildSupportGarnishmentFormProps): UseChildSupportGarnishmentFormResult

Headless hook for creating or updating a child-support garnishment.

Remarks

Unlike standard garnishments, child support requires agency-specific attributes (case number, order number, remittance number) that vary by state, plus an optional county selection when the state has multiple counties. The hook loads the agency catalog from the Gusto API, derives which attributes the selected state requires, and exposes the right Fields conditionally.

Presence or absence of garnishmentId selects the API verb: omit it to POST a new garnishment, supply it to PUT updates against the existing row. For non-child-support deductions (court-ordered garnishments and post-tax custom), use useDeductionForm instead.

Example

Example

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

function ChildSupportPage({ employeeId, garnishmentId }: { employeeId: string; garnishmentId?: string }) {
  const form = useChildSupportGarnishmentForm({ employeeId, garnishmentId })

  if (form.isLoading) return <p>Loading…</p>

  const { Fields } = form.form

  return (
    <SDKFormProvider formHookResult={form}>
      <form
        onSubmit={e => {
          e.preventDefault()
          void form.actions.onSubmit()
        }}
      >
        <Fields.State
          label="Agency"
          getOptionLabel={entry => entry.name}
          validationMessages={{ REQUIRED: 'Required' }}
        />
        {Fields.CaseNumber && (
          <Fields.CaseNumber label="Case number" validationMessages={{ REQUIRED: 'Required' }} />
        )}
        <Fields.Amount
          label="Percentage of paycheck"
          validationMessages={{
            REQUIRED: 'Required',
            PERCENT_OUT_OF_RANGE: 'Must be between 0 and 100',
          }}
        />
        <button type="submit">Save</button>
      </form>
    </SDKFormProvider>
  )
}

Props

UseChildSupportGarnishmentFormProps

Configuration options for useChildSupportGarnishmentForm.

Remarks

Presence or absence of garnishmentId selects the API verb — see the garnishmentId field description.

Property	Type	Description
employeeId	string	UUID of the employee whose child-support garnishment is being created or edited.
defaultValues?	Partial<ChildSupportGarnishmentFormData>	Pre-fill form values. Server data takes precedence on update.
garnishmentId?	string	When set, loads that garnishment and updates it (PUT). When omitted, the form is in create mode (POST).
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'.

Returns

UseChildSupportGarnishmentFormResult

A HookLoadingResult while loading, or a UseChildSupportGarnishmentFormReady once ready.

UseChildSupportGarnishmentFormResult

UseChildSupportGarnishmentFormResult = HookLoadingResult | UseChildSupportGarnishmentFormReady

Return value of useChildSupportGarnishmentForm.

Remarks

Discriminated union: HookLoadingResult while the agency catalog (and, in update mode, the existing garnishment) is loading; UseChildSupportGarnishmentFormReady once data is ready.

---

UseChildSupportGarnishmentFormReady

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

Remarks

Discriminated by isLoading: false. Extends BaseFormHookReady with the child-support-specific data, status, actions, and form.Fields shape. Static, entity-derived values live under data.*; reactive values that flip with form input live under status.*.

Property	Type	Description
actions	object	Submission action.
actions.onSubmit	() => Promise<HookSubmitResult<Garnishment> | undefined>	Submits the form. Returns the saved garnishment + mode on success, or undefined when validation fails or the request errored.
data	object	Child-support-specific data payload: the available agencies, counties for the selected state, and the loaded garnishment for update mode.
data.agencies	StateFieldEntry[]	Agencies offered as State options; raw entries the consumer can use with getOptionLabel for translated names.
data.counties	CountyEntry[]	Counties for the currently selected state. Empty array when no state is selected.
data.deduction	Garnishment | null	The garnishment 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	ChildSupportGarnishmentFormFields	-
form.fieldsMetadata	ChildSupportGarnishmentFormFieldsMetadata	-
form.getFormSubmissionValues	() => ChildSupportGarnishmentFormData | undefined	-
form.hookFormInternals	HookFormInternals<ChildSupportGarnishmentFormData>	-
isLoading	false	Always false in this branch; discriminates from HookLoadingResult.
status	object	Submission state and reactive flags derived from current form input.
status.isManualPaymentRequired	boolean	Mirrors selectedAgency.manualPaymentRequired; convenient for showing a warning alert.
status.isPending	boolean	true while a create or update mutation is in flight.
status.mode	"create" | "update"	Reflects whether the next submit will POST a new garnishment or PUT an existing one.
status.requiredAttrKeys	ReadonlySet<"case_number" | "order_number" | "remittance_number">	Which required_attributes keys the selected agency declares.
status.selectedAgency	Agencies | null	The agency record matching the currently selected state.

Fields

ChildSupportGarnishmentFormFields

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

Remarks

Each property is either the field component or undefined. A field is undefined when conditions for rendering it aren't met — see each member for its visibility rule. Always null-check conditional fields (e.g. {Fields.FipsCode && <Fields.FipsCode ... />}) before rendering.

Property	Type	Description
Amount	ComponentType<AmountFieldProps>	Bound to amount. Percent-of-paycheck input (0–100). Always available.
PaymentPeriod	ComponentType<PaymentPeriodFieldProps>	Bound to paymentPeriod. Payment period select. Always available.
PayPeriodMaximum	ComponentType<PayPeriodMaximumFieldProps>	Bound to payPeriodMaximum. Per-pay-period currency cap input. Always available.
State	ComponentType<StateFieldProps>	Bound to state. Agency (state) select. Always available.
CaseNumber	ComponentType<CaseNumberFieldProps> | undefined	Bound to caseNumber. Only available when the selected agency requires case_number.
FipsCode	ComponentType<FipsCodeFieldProps> | undefined	Bound to fipsCode. Only available when the selected agency has more than one fips code, or the sole code is county-scoped (not an "all counties" auto-pick).
OrderNumber	ComponentType<OrderNumberFieldProps> | undefined	Bound to orderNumber. Only available when the selected agency requires order_number.
RemittanceNumber	ComponentType<RemittanceNumberFieldProps> | undefined	Bound to remittanceNumber. Only available when the selected agency requires remittance_number.

---

Amount

Bound to amount. Percent-of-paycheck input (0–100). Always available.

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

ChildSupportGarnishmentAmountFieldProps

HookFieldProps<NumberInputHookFieldProps<ChildSupportGarnishmentAmountValidation>>

Props accepted by useChildSupportGarnishmentForm's Fields.Amount 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<ChildSupportGarnishmentAmountValidation>	Custom error text keyed by validation error code.

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

---

CaseNumber

Bound to caseNumber. Only available when the selected agency requires case_number.

{form.Fields.CaseNumber && (
  <form.Fields.CaseNumber
    label="Case number"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

CaseNumberFieldProps

HookFieldProps<TextInputHookFieldProps<ChildSupportGarnishmentRequiredValidation>>

Props accepted by useChildSupportGarnishmentForm's Fields.CaseNumber 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<ChildSupportGarnishmentRequiredValidation>	Custom error text keyed by validation error code.

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

---

FipsCode

Bound to fipsCode. Only available when the selected agency has more than one fips code, or the sole code is county-scoped (not an "all counties" auto-pick).

{form.Fields.FipsCode && (
  <form.Fields.FipsCode
    label="Fips code"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

FipsCodeFieldProps

HookFieldProps<SelectHookFieldProps<ChildSupportGarnishmentRequiredValidation, CountyEntry>>

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

Also accepts description, formHookResult, portalContainer from SelectHookFieldProps.

---

OrderNumber

Bound to orderNumber. Only available when the selected agency requires order_number.

{form.Fields.OrderNumber && (
  <form.Fields.OrderNumber
    label="Order number"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

OrderNumberFieldProps

HookFieldProps<TextInputHookFieldProps<ChildSupportGarnishmentRequiredValidation>>

Props accepted by useChildSupportGarnishmentForm's Fields.OrderNumber 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<ChildSupportGarnishmentRequiredValidation>	Custom error text keyed by validation error code.

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

---

PaymentPeriod

Bound to paymentPeriod. Payment period select. Always available.

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

PaymentPeriodFieldProps

HookFieldProps<SelectHookFieldProps<ChildSupportGarnishmentRequiredValidation, PaymentPeriod>>

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

Also accepts description, formHookResult, portalContainer from SelectHookFieldProps.

---

PayPeriodMaximum

Bound to payPeriodMaximum. Per-pay-period currency cap input. Always available.

<form.Fields.PayPeriodMaximum
  label="Pay period maximum"
  validationMessages={{ REQUIRED: '…', NEGATIVE_AMOUNT: '…' }}
/>

PayPeriodMaximumFieldProps

HookFieldProps<NumberInputHookFieldProps<PayPeriodMaximumValidation>>

Props accepted by useChildSupportGarnishmentForm's Fields.PayPeriodMaximum 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<PayPeriodMaximumValidation>	Custom error text keyed by validation error code.

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

---

RemittanceNumber

Bound to remittanceNumber. Only available when the selected agency requires remittance_number.

{form.Fields.RemittanceNumber && (
  <form.Fields.RemittanceNumber
    label="Remittance number"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

RemittanceNumberFieldProps

HookFieldProps<TextInputHookFieldProps<ChildSupportGarnishmentRequiredValidation>>

Props accepted by useChildSupportGarnishmentForm's Fields.RemittanceNumber 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<ChildSupportGarnishmentRequiredValidation>	Custom error text keyed by validation error code.

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

---

State

Bound to state. Agency (state) select. Always available.

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

ChildSupportGarnishmentStateFieldProps

HookFieldProps<SelectHookFieldProps<ChildSupportGarnishmentRequiredValidation, StateFieldEntry>>

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

Also accepts description, formHookResult, portalContainer from SelectHookFieldProps.

Validations

ChildSupportGarnishmentAmountValidation

ChildSupportGarnishmentAmountValidation = ChildSupportGarnishmentRequiredValidation | ChildSupportGarnishmentPercentValidation

Validation error codes emitted by the amount field of useChildSupportGarnishmentForm.

Remarks

Use these as keys in validationMessages on Fields.Amount. The field accepts a percentage of paycheck (0–100). See ChildSupportGarnishmentFormErrorCodes for the full description of each code.

---

ChildSupportGarnishmentNegativeAmountValidation

ChildSupportGarnishmentNegativeAmountValidation = "NEGATIVE_AMOUNT"

The negative-amount error code produced by useChildSupportGarnishmentForm's currency fields.

Remarks

Used as a validationMessages key on Fields.PayPeriodMaximum. See ChildSupportGarnishmentFormErrorCodes.

---

ChildSupportGarnishmentPercentValidation

ChildSupportGarnishmentPercentValidation = "PERCENT_OUT_OF_RANGE"

The percent-out-of-range error code produced by useChildSupportGarnishmentForm's percentage field.

Remarks

Used as a validationMessages key on Fields.Amount (the percent-of-paycheck input). See ChildSupportGarnishmentFormErrorCodes.

---

ChildSupportGarnishmentRequiredValidation

ChildSupportGarnishmentRequiredValidation = "REQUIRED"

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

Remarks

Used as the validationMessages key for the state, county (fips code), case number, order number, remittance number, and payment-period fields. See ChildSupportGarnishmentFormErrorCodes.

---

PayPeriodMaximumValidation

PayPeriodMaximumValidation = ChildSupportGarnishmentRequiredValidation | ChildSupportGarnishmentNegativeAmountValidation

Validation error codes emitted by the payPeriodMaximum field of useChildSupportGarnishmentForm.

Remarks

Use these as keys in validationMessages on Fields.PayPeriodMaximum. See ChildSupportGarnishmentFormErrorCodes for the full description of each code.

Utility types

ChildSupportGarnishmentFormData

Shape of the values managed by the child support garnishment form.

Properties

Property	Type
amount	number
caseNumber	string
fipsCode	string
orderNumber	string
paymentPeriod	"Every week" | "Every other week" | "Twice per month" | "Monthly"
payPeriodMaximum	number
remittanceNumber	string
state	string

---

ChildSupportGarnishmentFormErrorCode

ChildSupportGarnishmentFormErrorCode = "REQUIRED" | "NEGATIVE_AMOUNT" | "PERCENT_OUT_OF_RANGE"

Union of validation error code strings emitted by the child support garnishment form schema.

---

ChildSupportGarnishmentFormErrorCodes

const ChildSupportGarnishmentFormErrorCodes: object

Validation error codes emitted by the child support garnishment form schema. Map these codes to localized copy in validationMessages when composing the hook.

Type Declaration

Name	Type
NEGATIVE_AMOUNT	"NEGATIVE_AMOUNT"
PERCENT_OUT_OF_RANGE	"PERCENT_OUT_OF_RANGE"
REQUIRED	"REQUIRED"

---

ChildSupportGarnishmentFormFieldsMetadata

Field	Type
amount	FieldMetadata
caseNumber	FieldMetadata
fipsCode	FieldMetadataWithOptions<CountyEntry>
orderNumber	FieldMetadata
paymentPeriod	FieldMetadataWithOptions<"Every week" | "Every other week" | "Twice per month" | "Monthly">
payPeriodMaximum	FieldMetadata
remittanceNumber	FieldMetadata
state	FieldMetadataWithOptions<StateFieldEntry>

Per-field metadata returned by useChildSupportGarnishmentForm as form.fieldsMetadata.

Remarks

Carries per-field isRequired, isDisabled, label, description, and option entries derived from the schema and form state. Use these to drive UI such as disabled state or option lists when not relying on the pre-bound ChildSupportGarnishmentFormFields components.

---

CountyEntry

CountyEntry = object

Raw county entry exposed on useChildSupportGarnishmentForm's data.counties and as the entries shape for the FipsCode select.

Remarks

county is null for "all counties" entries — the agency's single county record represents the whole state. Supply getOptionLabel on Fields.FipsCode to translate the county name into a localized label.

Properties

Property	Type	Description
county	string | null	The county name, or null for an "all counties" entry covering the whole state.
fipsCode	string	The FIPS code for the county.

---

StateFieldEntry

StateFieldEntry = object

Raw agency entry exposed on useChildSupportGarnishmentForm's data.agencies and as the entries shape for the State select.

Remarks

Supply getOptionLabel on Fields.State to translate the agency name into a localized label — the SDK's option-label fallback is the agency state code.

Properties

Property	Type	Description
name	string	The agency name as returned by the Gusto API.
state	string	The agency's state code (e.g. AK).
manualPaymentRequired?	boolean	True when the agency requires payments to be remitted manually rather than through Gusto.

---

SUPPORTED_REQUIRED_ATTR_KEYS

const SUPPORTED_REQUIRED_ATTR_KEYS: readonly ["case_number", "order_number", "remittance_number"]

Child support attribute keys that the form recognizes. Each state agency declares which of these keys it requires; the hook exposes the resolved subset via requiredAttrKeys so callers can drive their own UI on which caseNumber / orderNumber / remittanceNumber fields are required.

---

SupportedRequiredAttrKey

SupportedRequiredAttrKey = "case_number" | "order_number" | "remittance_number"

Union of child support attribute key strings recognized by the form.

Endpoints

Method	Path
GET	/v1/employees/:employeeId/garnishments
POST	/v1/employees/:employeeId/garnishments
PUT	/v1/garnishments/:garnishmentId
GET	/v1/garnishments/child_support