useFederalTaxesForm

useFederalTaxesForm(props: UseFederalTaxesFormProps): HookLoadingResult | UseFederalTaxesFormReady

Headless hook for updating an employee's federal tax (W-4) withholding information — filing status, multiple-jobs flag, dependents, other income, deductions, and extra withholding.

Remarks

The federal tax record is created automatically with the employee, so this hook is always in update mode. Only the revised 2020 W-4 format is supported for updates. By default only filingStatus is required; promote any of twoJobs, dependentsAmount, otherIncome, deductions, or extraWithholding to required via optionalFieldsToRequire.update.

Example

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

function FederalTaxesPage({ employeeId }: { employeeId: string }) {
  const federalTaxes = useFederalTaxesForm({ employeeId })

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

  const { Fields } = federalTaxes.form

  return (
    <SDKFormProvider formHookResult={federalTaxes}>
      <form
        onSubmit={e => {
          e.preventDefault()
          void federalTaxes.actions.onSubmit()
        }}
      >
        <Fields.FilingStatus label="Federal filing status" />
        <Fields.TwoJobs label="Multiple jobs (2c)" />
        <Fields.DependentsAmount label="Dependents" />
        <Fields.OtherIncome label="Other income" />
        <Fields.Deductions label="Deductions" />
        <Fields.ExtraWithholding label="Extra withholding" />
        <button type="submit" disabled={federalTaxes.status.isPending}>Save</button>
      </form>
    </SDKFormProvider>
  )
}

Props

UseFederalTaxesFormProps

Configuration options for useFederalTaxesForm.

Remarks

The federal tax record is created automatically with the employee, so the hook is always in update mode and only employeeId is required.

Property	Type	Description
`employeeId`	`string`	UUID of the employee whose federal tax record is being updated.
`defaultValues?`	`Partial`<`FederalTaxesFormData`>	Pre-fill form values. Server data takes precedence when the employee already has values on file.
`optionalFieldsToRequire?`	`FederalTaxesOptionalFieldsToRequire`	Override fields that are optional on update to be required. By default only `filingStatus` is required; pass `{ update: ['twoJobs', 'dependentsAmount', 'otherIncome', 'deductions', 'extraWithholding'] }` to require any subset. See FederalTaxesOptionalFieldsToRequire.
`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'`.

Returns

HookLoadingResult | UseFederalTaxesFormReady

A HookLoadingResult while data is loading, or a UseFederalTaxesFormReady once the federal tax record is loaded.

UseFederalTaxesFormResult

UseFederalTaxesFormResult = HookLoadingResult | UseFederalTaxesFormReady

Discriminated union returned by useFederalTaxesForm — either the loading state or the ready state.

Remarks

Use this type when threading the hook result through helpers (e.g. presentational components). Discriminate on isLoading to narrow to UseFederalTaxesFormReady.

UseFederalTaxesFormReady

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

Remarks

Discriminated by isLoading: false. Extends BaseFormHookReady with the federal-taxes specific data, status, and actions.

Property	Type	Description
`actions`	`object`	Submit actions exposed by the hook.
`actions.onSubmit`	() => `Promise`<`HookSubmitResult`<`EmployeeFederalTax`> \| `undefined`>	Validates the form, runs the update mutation, and resolves to a HookSubmitResult containing the updated record. Resolves to `undefined` on validation failure or mutation error.
`data`	`object`	The loaded federal tax record.
`data.employeeFederalTax`	`EmployeeFederalTax`	The current federal tax record for the employee.
`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`	`FederalTaxesFormFields`	-
`form.fieldsMetadata`	`FederalTaxesFieldsMetadata`	-
`form.getFormSubmissionValues`	() => `FederalTaxesFormData` \| `undefined`	-
`form.hookFormInternals`	`HookFormInternals`<`FederalTaxesFormData`>	-
`isLoading`	`false`	Always `false` in this branch; discriminates from HookLoadingResult.
`status`	`object`	Submission state. `mode` is always `'update'` — the federal tax record is created with the employee, so this hook has no create mode.
`status.isPending`	`boolean`	`true` while the update mutation is in flight.
`status.mode`	`"update"`	Always `'update'` — the federal tax record is created when the employee is created.

Fields

FederalTaxesFormFields

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

Property	Type	Description
`Deductions`	`ComponentType`<`DeductionsFieldProps`>	Bound to `deductions`. Deductions (Step 4b) currency input.
`DependentsAmount`	`ComponentType`<`DependentsAmountFieldProps`>	Bound to `dependentsAmount`. Dependents amount (Step 3) currency input.
`ExtraWithholding`	`ComponentType`<`ExtraWithholdingFieldProps`>	Bound to `extraWithholding`. Extra withholding (Step 4c) currency input.
`FilingStatus`	`ComponentType`<`FilingStatusFieldProps`>	Bound to `filingStatus`. Filing status select.
`OtherIncome`	`ComponentType`<`OtherIncomeFieldProps`>	Bound to `otherIncome`. Other income (Step 4a) currency input.
`TwoJobs`	`ComponentType`<`TwoJobsFieldProps`>	Bound to `twoJobs`. Multiple-jobs (Step 2c) radio group.

Deductions

Bound to deductions. Deductions (Step 4b) currency input.

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

DeductionsFieldProps

HookFieldProps<NumberInputHookFieldProps<FederalTaxesRequiredValidation>>

Props accepted by useFederalTaxesForm's Fields.Deductions 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`<`FederalTaxesRequiredValidation`>	Custom error text keyed by validation error code.

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

DependentsAmount

Bound to dependentsAmount. Dependents amount (Step 3) currency input.

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

DependentsAmountFieldProps

HookFieldProps<NumberInputHookFieldProps<FederalTaxesRequiredValidation>>

Props accepted by useFederalTaxesForm's Fields.DependentsAmount 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`<`FederalTaxesRequiredValidation`>	Custom error text keyed by validation error code.

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

ExtraWithholding

Bound to extraWithholding. Extra withholding (Step 4c) currency input.

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

ExtraWithholdingFieldProps

HookFieldProps<NumberInputHookFieldProps<FederalTaxesRequiredValidation>>

Props accepted by useFederalTaxesForm's Fields.ExtraWithholding 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`<`FederalTaxesRequiredValidation`>	Custom error text keyed by validation error code.

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

FilingStatus

Bound to filingStatus. Filing status select.

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

FilingStatusFieldProps

HookFieldProps<SelectHookFieldProps<FederalTaxesRequiredValidation, FilingStatusValue>>

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

Also accepts description, formHookResult, portalContainer from SelectHookFieldProps.

OtherIncome

Bound to otherIncome. Other income (Step 4a) currency input.

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

OtherIncomeFieldProps

HookFieldProps<NumberInputHookFieldProps<FederalTaxesRequiredValidation>>

Props accepted by useFederalTaxesForm's Fields.OtherIncome 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`<`FederalTaxesRequiredValidation`>	Custom error text keyed by validation error code.

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

TwoJobs

Bound to twoJobs. Multiple-jobs (Step 2c) radio group.

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

TwoJobsFieldProps

HookFieldProps<RadioGroupHookFieldProps<FederalTaxesRequiredValidation, boolean>>

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

Also accepts description, formHookResult from RadioGroupHookFieldProps.

Validations

FederalTaxesRequiredValidation

FederalTaxesRequiredValidation = "REQUIRED"

The required-field error code produced by useFederalTaxesForm fields.

Remarks

Used as the validationMessages key for every federal taxes field. See FederalTaxesErrorCodes.

Utility types

FederalTaxesErrorCode

FederalTaxesErrorCode = "REQUIRED"

Union of validation error code strings emitted by the federal taxes form schema.

FederalTaxesErrorCodes

const FederalTaxesErrorCodes: object

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

Type Declaration

Name	Type
`REQUIRED`	`"REQUIRED"`

FederalTaxesField

FederalTaxesField = "deductions" | "extraWithholding" | "filingStatus" | "otherIncome" | "twoJobs" | "dependentsAmount"

Field names accepted by the federal taxes form.

FederalTaxesFieldsMetadata

Field	Type
`deductions`	`FieldMetadata`
`dependentsAmount`	`FieldMetadata`
`extraWithholding`	`FieldMetadata`
`filingStatus`	`FieldMetadataWithOptions`<`"Single"` \| `"Married"` \| `"Head of Household"` \| `"Exempt from withholding"`>
`otherIncome`	`FieldMetadata`
`twoJobs`	`FieldMetadataWithOptions`<`boolean`>

Metadata for each useFederalTaxesForm field, exposed on form.fieldsMetadata.

Remarks

Includes per-field isDisabled, isRequired, and the dynamic option list for select and radio fields (filingStatus, twoJobs).

FederalTaxesFormData

Shape of the values managed by the federal taxes form.

Properties

Property	Type
`deductions`	`number`
`dependentsAmount`	`number`
`extraWithholding`	`number`
`filingStatus`	`string`
`otherIncome`	`number`
`twoJobs`	`boolean`

FederalTaxesOptionalFieldsToRequire

FederalTaxesOptionalFieldsToRequire = OptionalFieldsToRequire<typeof requiredFieldsConfig>

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

FILING_STATUS_VALUES

const FILING_STATUS_VALUES: readonly ["Single", "Married", "Head of Household", "Exempt from withholding"]

Supported W-4 filing status values: single, married filing jointly, head of household, and exempt from withholding.

FilingStatusValue

FilingStatusValue = "Single" | "Married" | "Head of Household" | "Exempt from withholding"

Union of filing status values that the form accepts.

Endpoints

Method	Path
GET	`/v1/employees/:employeeUuid/federal_taxes`
PUT	`/v1/employees/:employeeUuid/federal_taxes`

Remarks​

Example​

Props​

UseFederalTaxesFormProps​

Returns​

UseFederalTaxesFormResult​

Remarks​

UseFederalTaxesFormReady​

Fields​

FederalTaxesFormFields​

Deductions​

DeductionsFieldProps​

DependentsAmount​

DependentsAmountFieldProps​

ExtraWithholding​

ExtraWithholdingFieldProps​

FilingStatus​

FilingStatusFieldProps​

OtherIncome​

OtherIncomeFieldProps​

TwoJobs​

TwoJobsFieldProps​

Validations​

FederalTaxesRequiredValidation​

Remarks​

Utility types​

FederalTaxesErrorCode​

FederalTaxesErrorCodes​

Type Declaration​

FederalTaxesField​

FederalTaxesFieldsMetadata​

Remarks​

FederalTaxesFormData​

Properties​

FederalTaxesOptionalFieldsToRequire​

FILING_STATUS_VALUES​

FilingStatusValue​

Endpoints​

Remarks

Example

Props

UseFederalTaxesFormProps

Returns

UseFederalTaxesFormResult

Remarks

UseFederalTaxesFormReady

Fields

FederalTaxesFormFields

Deductions

DeductionsFieldProps

DependentsAmount

DependentsAmountFieldProps

ExtraWithholding

ExtraWithholdingFieldProps

FilingStatus

FilingStatusFieldProps

OtherIncome

OtherIncomeFieldProps

TwoJobs

TwoJobsFieldProps

Validations

FederalTaxesRequiredValidation

Remarks

Utility types

FederalTaxesErrorCode

FederalTaxesErrorCodes

Type Declaration

FederalTaxesField

FederalTaxesFieldsMetadata

Remarks

FederalTaxesFormData

Properties

FederalTaxesOptionalFieldsToRequire

FILING_STATUS_VALUES

FilingStatusValue

Endpoints