useEmployeeStateTaxesForm

useEmployeeStateTaxesForm(props: UseEmployeeStateTaxesFormProps): UseEmployeeStateTaxesFormResult

Headless form hook for updating an employee's state tax withholding answers. The set of questions is driven by the API response per state, so form.Fields is an array of state groups with discriminated, render-ready Field components rather than a fixed named object.

Remarks

The state-tax record(s) are created automatically with the employee, so this hook is always in update mode. When the form has no states with submittable answers (e.g. an employee in a no-income-tax state), submit resolves with the existing record list without making a network request.

Example

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

function StateTaxesPage({ employeeId }: { employeeId: string }) {
  const stateTaxes = useEmployeeStateTaxesForm({ employeeId })

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

  return <StateTaxesFormReady stateTaxes={stateTaxes} />
}

function StateTaxesFormReady({
  stateTaxes,
}: {
  stateTaxes: UseEmployeeStateTaxesFormReady
}) {
  const handleSubmit = async () => {
    const result = await stateTaxes.actions.onSubmit()
    if (result) console.log('Updated state tax records:', result.data)
  }

  return (
    <SDKFormProvider formHookResult={stateTaxes}>
      <form
        onSubmit={e => {
          e.preventDefault()
          void handleSubmit()
        }}
      >
        {stateTaxes.form.Fields.map(group => (
          <section key={group.state}>
            <h2>{group.state}</h2>
            {group.questions.map(question => (
              <question.Field key={question.questionId} />
            ))}
          </section>
        ))}
        <button type="submit" disabled={stateTaxes.status.isPending}>
          Save
        </button>
      </form>
    </SDKFormProvider>
  )
}

Props

UseEmployeeStateTaxesFormProps

Options accepted by useEmployeeStateTaxesForm.

Property	Type	Description
`employeeId`	`string`	The UUID of the employee whose state taxes are being updated.
`isAdmin?`	`boolean`	When `true`, admin-only questions are visible and submitted. When `false`, they are filtered out and the surfaced answer for those questions is preserved unchanged on submit.
`shouldFocusError?`	`boolean`	Auto-focus the first invalid field on submit. Defaults to `true`. Set to `false` when composing with other forms.
`validationMode?`	`"onChange"` \| `"onBlur"` \| `"onSubmit"` \| `"onTouched"` \| `"all"`	When validation runs. Passed through to react-hook-form. Defaults to `'onSubmit'`.

Returns

UseEmployeeStateTaxesFormResult

A loading result while data is fetching, or a ready result with form data, fields, status, actions, and error handling.

UseEmployeeStateTaxesFormResult

UseEmployeeStateTaxesFormResult = HookLoadingResult | UseEmployeeStateTaxesFormReady

Discriminated union returned by useEmployeeStateTaxesForm. Loading branch carries only errorHandling; ready branch carries form data, fields, status, and actions.

UseEmployeeStateTaxesFormReady

Ready-state return value of useEmployeeStateTaxesForm — the isLoading: false branch of UseEmployeeStateTaxesFormResult.

Property	Type	Description
`actions`	`object`	Form actions.
`actions.onSubmit`	() => `Promise`<`HookSubmitResult`<`EmployeeStateTaxesList`[]> \| `undefined`>	Validates and submits the form, resolving to the updated records on success or `undefined` when validation blocked the submit.
`data`	`object`	Current per-state tax records returned by the server.
`data.employeeStateTaxes`	`EmployeeStateTaxesList`[]	-
`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`	`StateTaxFields`	-
`form.fieldsMetadata`	`EmployeeStateTaxesFieldsMetadata`	-
`form.getFormSubmissionValues`	() => `EmployeeStateTaxesFormData` \| `undefined`	-
`form.hookFormInternals`	`HookFormInternals`<`EmployeeStateTaxesFormData`>	-
`isLoading`	`false`	Always `false` in this branch; discriminates from HookLoadingResult.
`status`	`object`	Submission status. `mode` is always `'update'` since state-tax records are created with the employee.
`status.isPending`	`boolean`	-
`status.mode`	`"update"`	-

Fields

StateTaxFields

StateTaxFields = StateTaxFieldsGroup[]

Iterable, render-ready group + question entries with bound Field components, grouped by state.

Example

The value exposed on form.Fields: one entry per state, each carrying its questions as pre-bound Field components you render directly.

function StateTaxQuestions({ fields }: { fields: StateTaxFields }) {
  return fields.map(group => (
    <section key={group.state}>
      <h3>{group.state}</h3>
      {group.questions.map(question => (
        <question.Field key={question.questionId} />
      ))}
    </section>
  ))
}

StateTaxFieldsGroup

Group of state-tax questions for a single jurisdiction returned by useStateFields.

Properties

Property	Type	Description
`questions`	`StateTaxQuestionFieldEntry`[]	Ordered list of question entries for this state, post admin-only filtering.
`state`	`string`	Two-letter state code.

StateTaxQuestionFieldEntry

StateTaxQuestionFieldEntry = SelectStateTaxQuestion | RadioStateTaxQuestion | TextStateTaxQuestion | NumberStateTaxQuestion | CurrencyStateTaxQuestion | DateStateTaxQuestion

One question entry within a StateTaxFieldsGroup, discriminated by type to identify which input variant the question uses. Each entry carries a Field component pre-bound to its API-supplied metadata so callers can render the input directly.

CurrencyStateTaxQuestion

A state-tax question that renders as a currency-formatted number input. Includes read-only question metadata from the API and a bound currency field, exposed as <question.Field />.