useCompensationForm

useCompensationForm(input: UseCompensationFormProps): HookLoadingResult | UseCompensationFormReady

Headless hook for creating or updating a compensation row on a job — FLSA classification, pay rate, payment unit, effective date, and optional minimum-wage adjustment.

Remarks

Companion hook to useJobForm. Jobs and their compensations are separate entities in the Gusto API and this hook focuses exclusively on the compensation side. Presence of compensationId selects the verb:

Hook config / submit options	Mode	API call
`{ jobId, compensationId }`	update	`PUT /v1/compensations/:compensationId` (with `version`)
`{ jobId }` (no `compensationId`)	create	`POST /v1/jobs/:jobId/compensations`
`{ employeeId }` + submit `{ jobId, compensationId, compensationVersion }`	update	`PUT /v1/compensations/:compensationId` (with the supplied `version`)
`{ employeeId }` + submit `{ jobId }` (no `compensationId`)	create	`POST /v1/jobs/:options.jobId/compensations`

Use the submit-options form for the onboarding stub-fill chain: after useJobForm.actions.onSubmit() creates a job, capture the auto-created compensation's UUID and version from the response, and pass them as { jobId, compensationId, compensationVersion } to this hook's onSubmit to PUT the stub.

The hook exposes several derived helpers for driving UX — static entity-derived values under data.* (effective-date bounds, pending future compensations) and reactive flags under status.* (the willDeleteSecondaryJobs carve-out, plus FLSA-specific alerts for commission-only and owner classifications). When willDeleteSecondaryJobs is true in update mode, the hook also locks the effectiveDate field (forces to today, renders disabled) until the FLSA selection is reverted.

Example

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

function CompensationForm({ employeeId, jobId }: { employeeId: string; jobId: string }) {
  const comp = useCompensationForm({ employeeId, jobId })
  if (comp.isLoading) return null

  const { Fields } = comp.form
  return (
    <form onSubmit={e => { e.preventDefault(); comp.actions.onSubmit() }}>
      <SDKFormProvider formHookResult={comp}>
        {Fields.FlsaStatus && <Fields.FlsaStatus label="Employee type" />}
        <Fields.Rate label="Compensation amount" />
        <Fields.PaymentUnit label="Payment unit" />
        {Fields.EffectiveDate && <Fields.EffectiveDate label="Effective date" />}
      </SDKFormProvider>
      {comp.status.willDeleteSecondaryJobs && (
        <p>Saving will remove this employee's secondary jobs.</p>
      )}
      <button type="submit" disabled={comp.status.isPending}>Save</button>
    </form>
  )
}

Props

UseCompensationFormProps

Configuration options for useCompensationForm.

Remarks

Presence or absence of compensationId selects the API verb — see the compensationId field description. employeeId is optional so the hook can be composed alongside an employee-creation step. jobId is optional in update mode (derived from the loaded compensation) and required in create mode (scopes the POST); supply it at submit time via CompensationSubmitOptions.jobId when the parent job is created in the same submit chain.

Property	Type	Description
`compensationId?`	`string`	Present → update mode (PUT /v1/compensations/:id). Omitted → create mode (POST /v1/jobs/:jobId/compensations).
`defaultValues?`	`Partial`<`CompensationFormData`>	Pre-fill form values. Server data takes precedence on update mode.
`employeeId?`	`string`	UUID of the employee whose compensation is being created or edited. Drives data fetching for derived helpers (jobs list, work address, minimum wages). May be omitted when composing alongside an employee-creation step.
`jobId?`	`string`	The parent job's UUID. Required in create mode (scopes `POST /v1/jobs/:jobId/compensations`). Optional in update mode — the parent job is derived from the loaded compensation.
`optionalFieldsToRequire?`	`CompensationOptionalFieldsToRequire`	Override fields that are optional on a given mode to be required. See CompensationOptionalFieldsToRequire.
`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'`.
`withEffectiveDateField?`	`boolean`	When `false`, hides `Fields.EffectiveDate` (becomes `undefined`) and removes `effectiveDate` from schema validation. In this mode the hook does not read any form value at submit time — `effective_date` is omitted from the request body unless explicitly supplied via CompensationSubmitOptions.effectiveDate. This matches the options-only convention of other form hooks, and means the `willDeleteSecondaryJobs` carve-out's form-state side effects do not leak onto the wire (there is no field to render them in anyway). Defaults to `true`.

Returns

HookLoadingResult | UseCompensationFormReady

A HookLoadingResult while data is loading, or a UseCompensationFormReady once ready.

UseCompensationFormResult

UseCompensationFormResult = HookLoadingResult | UseCompensationFormReady

Discriminated union returned by useCompensationForm — 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 UseCompensationFormReady.

UseCompensationFormReady

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

Remarks

Discriminated by isLoading: false. Extends BaseFormHookReady with the compensation-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`	Submit actions exposed by the hook.
`actions.onSubmit`	(`options?`: `CompensationSubmitOptions`) => `Promise`<`HookSubmitResult`<`Compensation`> \| `undefined`>	Validates the form, runs the appropriate create/update mutation, and resolves to a HookSubmitResult containing the saved compensation. Resolves to `undefined` on validation failure or mutation error. Accepts CompensationSubmitOptions for threading IDs/version into the onboarding stub-fill chain.
`data`	`object`	Compensation-specific data payload: the loaded compensation, the parent job, available minimum wages, and effective-date bounds.
`data.compensation`	`Compensation` \| `null`	The compensation row loaded for update; `null` in create mode.
`data.currentJob`	`Job` \| `null`	The parent job. In update mode it's derived from the loaded compensation; in create mode it's looked up by `jobId`. `null` if neither resolves.
`data.hasPendingFutureCompensation`	`boolean`	True when at least one future-dated compensation already exists for this job.
`data.maximumEffectiveDate`	`string` \| `null`	Upper bound for `effectiveDate` — the next scheduled future compensation's effective date, when one exists.
`data.minimumEffectiveDate`	`string` \| `null`	Lower bound for `effectiveDate` (typically the parent job's hire date).
`data.minimumWages`	`MinimumWage`[]	Minimum wages available at the employee's active work location. Empty when no location is set or no minimums are defined.
`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`	`CompensationFormFields`	-
`form.fieldsMetadata`	`CompensationFieldsMetadata`	-
`form.getFormSubmissionValues`	() => `CompensationFormData` \| `undefined`	-
`form.hookFormInternals`	`HookFormInternals`<`CompensationFormData`>	-
`isLoading`	`false`	Always `false` in this branch; discriminates from HookLoadingResult.
`status`	`object`	Submission state and reactive flags derived from current form input. `isPending` is `true` while a create/update mutation is in flight; `mode` reflects whether the next submit will create or update; the `show*Alert` flags drive FLSA-specific inline warnings.
`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 compensation or PUT an existing one.
`status.showCommissionFederalMinimumPayAlert`	`boolean`	True when the current `flsaStatus` is `COMMISSION_ONLY_EXEMPT` (Commission Only/No Overtime). Render the federal-minimum-pay warning alert when this flag is true. While this flag is true, `Fields.Rate` and `Fields.PaymentUnit` are also `undefined` (the hook forces `rate=0`, `paymentUnit=YEAR` on the form values).
`status.showCommissionMinimumWageAlert`	`boolean`	True when the current `flsaStatus` is `COMMISSION_ONLY_NONEXEMPT` (Commission Only/Eligible for overtime). Render the local-minimum-wage warning alert when this flag is true. While this flag is true, `Fields.Rate` and `Fields.PaymentUnit` are also `undefined` (the hook forces `rate=0`, `paymentUnit=YEAR` on the form values).
`status.showOwnerSalaryAlert`	`boolean`	True when the current `flsaStatus` is `OWNER` (Owner's draw). Render an informational alert noting that the IRS requires S-corp owners to pay themselves a reasonable salary for similar work before taking distributions.
`status.willDeleteSecondaryJobs`	`boolean`	True when submitting the form right now would delete the employee's secondary jobs server-side (the "carve-out" branch). Reactive: derived from the current `flsaStatus` form value, the loaded compensation, and the other-jobs count, so this flips as you change inputs. Conditions: update mode, the loaded compensation is Nonexempt, the form's `flsaStatus` has been changed to a non-Nonexempt value, and the employee has at least one secondary job. While this flag is true the hook also takes the `effectiveDate` field over: it forces the form value to today (so submits route through a PUT that immediately deletes secondaries) and exposes `fieldsMetadata.effectiveDate.isDisabled = true` so `Fields.EffectiveDate` renders as disabled. On revert (FLSA back to Nonexempt) the prior `effectiveDate` is restored. Render an inline warning keyed off this flag — no separate confirmation step is needed.

Fields

CompensationFormFields

Pre-bound field components exposed on useCompensationForm().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.FlsaStatus && <Fields.FlsaStatus ... />}) before rendering.

Property	Type	Description
`Title`	`ComponentType`<`TitleFieldProps`>	Bound to `title`. Title text input. Always available. Optional in both modes unless `optionalFieldsToRequire` requires it.
`AdjustForMinimumWage`	`ComponentType`<`AdjustForMinimumWageFieldProps`> \| `undefined`	Bound to `adjustForMinimumWage`. Minimum-wage adjustment checkbox. `undefined` unless `flsaStatus === Nonexempt`, the employee's work location has minimum wages, and the state supports tip credits.
`EffectiveDate`	`ComponentType`<`EffectiveDateFieldProps`> \| `undefined`	Bound to `effectiveDate`. Effective-date picker. `undefined` when `withEffectiveDateField: false`; supply the value via `CompensationSubmitOptions.effectiveDate` in that mode.
`FlsaStatus`	`ComponentType`<`FlsaStatusFieldProps`> \| `undefined`	Bound to `flsaStatus`. FLSA classification select. `undefined` when the status is not user-editable (e.g. secondary jobs that must match the primary).
`MinimumWageId`	`ComponentType`<`MinimumWageIdFieldProps`> \| `undefined`	Bound to `minimumWageId`. Minimum-wage selection. `undefined` unless `Fields.AdjustForMinimumWage` is rendered and checked.
`PaymentUnit`	`ComponentType`<`PaymentUnitFieldProps`> \| `undefined`	Bound to `paymentUnit`. Payment unit select. `undefined` for commission-only FLSA statuses (the hook forces `paymentUnit=Year`).
`Rate`	`ComponentType`<`RateFieldProps`> \| `undefined`	Bound to `rate`. Compensation amount input. `undefined` for commission-only FLSA statuses, which don't accept a partner-supplied rate.

AdjustForMinimumWage

Bound to adjustForMinimumWage. Minimum-wage adjustment checkbox. undefined unless flsaStatus === Nonexempt, the employee's work location has minimum wages, and the state supports tip credits.

{form.Fields.AdjustForMinimumWage && (
  <form.Fields.AdjustForMinimumWage label="Adjust for minimum wage" />
)}

AdjustForMinimumWageFieldProps

HookFieldProps<CheckboxHookFieldProps>

Props accepted by useCompensationForm's Fields.AdjustForMinimumWage component.

Property	Type	Description
`label`	`string`	Visible label rendered above the field.
`FieldComponent?`	`ComponentType`<`CheckboxProps`>	Replaces the default checkbox UI component; must accept the same props as `CheckboxProps`.

Also accepts description, formHookResult from CheckboxHookFieldProps.

EffectiveDate

Bound to effectiveDate. Effective-date picker. undefined when withEffectiveDateField: false; supply the value via CompensationSubmitOptions.effectiveDate in that mode.

{form.Fields.EffectiveDate && (
  <form.Fields.EffectiveDate
    label="Effective date"
    validationMessages={{
      REQUIRED: '…',
      EFFECTIVE_DATE_BEFORE_HIRE: '…',
      EFFECTIVE_DATE_BEFORE_MIN: '…',
    }}
  />
)}

CompensationEffectiveDateFieldProps

HookFieldProps<DatePickerHookFieldProps<CompensationEffectiveDateValidation>>

Props accepted by useCompensationForm's Fields.EffectiveDate component.

Property	Type	Description
`label`	`string`	Visible label rendered above the field.
`FieldComponent?`	`ComponentType`<`DatePickerProps`>	Replaces the default date picker UI component; must accept the same props as `DatePickerProps`.
`validationMessages?`	`ValidationMessages`<`CompensationEffectiveDateValidation`>	Custom error text keyed by validation error code.

Also accepts description, formHookResult, maxDate, minDate, portalContainer from DatePickerHookFieldProps.

FlsaStatus

Bound to flsaStatus. FLSA classification select. undefined when the status is not user-editable (e.g. secondary jobs that must match the primary).

{form.Fields.FlsaStatus && (
  <form.Fields.FlsaStatus
    label="Flsa status"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

FlsaStatusFieldProps

HookFieldProps<SelectHookFieldProps<CompensationRequiredValidation, FlsaStatusType>>

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

Also accepts description, formHookResult, portalContainer from SelectHookFieldProps.

MinimumWageId

Bound to minimumWageId. Minimum-wage selection. undefined unless Fields.AdjustForMinimumWage is rendered and checked.

{form.Fields.MinimumWageId && (
  <form.Fields.MinimumWageId
    label="Minimum wage id"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

MinimumWageIdFieldProps

HookFieldProps<SelectHookFieldProps<CompensationRequiredValidation, MinimumWage>>

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

Also accepts description, formHookResult, portalContainer from SelectHookFieldProps.

PaymentUnit

Bound to paymentUnit. Payment unit select. undefined for commission-only FLSA statuses (the hook forces paymentUnit=Year).

{form.Fields.PaymentUnit && (
  <form.Fields.PaymentUnit
    label="Payment unit"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

PaymentUnitFieldProps

HookFieldProps<SelectHookFieldProps<CompensationRequiredValidation, PaymentUnit>>

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

Also accepts description, formHookResult, portalContainer from SelectHookFieldProps.

Rate

Bound to rate. Compensation amount input. undefined for commission-only FLSA statuses, which don't accept a partner-supplied rate.

{form.Fields.Rate && (
  <form.Fields.Rate
    label="Rate"
    validationMessages={{
      REQUIRED: '…',
      RATE_MINIMUM: '…',
      RATE_EXEMPT_THRESHOLD: '…',
    }}
  />
)}

RateFieldProps

HookFieldProps<NumberInputHookFieldProps<RateValidation>>

Props accepted by useCompensationForm's Fields.Rate 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`<`RateValidation`>	Custom error text keyed by validation error code.

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

Title

Bound to title. Title text input. Always available. Optional in both modes unless optionalFieldsToRequire requires it.

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

CompensationTitleFieldProps

HookFieldProps<TextInputHookFieldProps<CompensationRequiredValidation>>

Props accepted by useCompensationForm's Fields.Title 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`<`CompensationRequiredValidation`>	Custom error text keyed by validation error code.

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

Validations

CompensationEffectiveDateValidation

CompensationEffectiveDateValidation = "REQUIRED" | "EFFECTIVE_DATE_BEFORE_HIRE" | "EFFECTIVE_DATE_BEFORE_MIN"

Validation error codes emitted by the effectiveDate field of useCompensationForm.

Remarks

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

CompensationRequiredValidation

CompensationRequiredValidation = "REQUIRED"

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

Remarks

Used as the validationMessages key for the title, FLSA status, payment unit, and minimum-wage selection fields. See CompensationErrorCodes.

RateValidation

RateValidation = "REQUIRED" | "RATE_MINIMUM" | "RATE_EXEMPT_THRESHOLD"

Validation error codes emitted by the rate field of useCompensationForm.

Remarks

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

Utility types

CompensationErrorCode

CompensationErrorCode = "REQUIRED" | "RATE_MINIMUM" | "RATE_EXEMPT_THRESHOLD" | "PAYMENT_UNIT_OWNER" | "PAYMENT_UNIT_COMMISSION" | "RATE_COMMISSION_ZERO" | "EFFECTIVE_DATE_BEFORE_HIRE" | "EFFECTIVE_DATE_BEFORE_MIN"

Union of every error code produced by the useCompensationForm schema.

CompensationErrorCodes

const CompensationErrorCodes: object

Validation error codes produced by the useCompensationForm schema.

Remarks

Use these constants as the keys in a field's validationMessages prop to map an error code to a user-facing message.

Code	When it triggers
`REQUIRED`	A required field is empty (per mode and `optionalFieldsToRequire`).
`RATE_MINIMUM`	`rate` is less than `$1.00` for non-commission FLSA statuses.
`RATE_EXEMPT_THRESHOLD`	FLSA `Exempt` employees must clear the federal salary threshold (annualized).
`PAYMENT_UNIT_OWNER`	`Owner` FLSA status requires `paymentUnit === 'Paycheck'`.
`PAYMENT_UNIT_COMMISSION`	Commission-only FLSA statuses require `paymentUnit === 'Year'`.
`RATE_COMMISSION_ZERO`	Commission-only FLSA statuses require `rate === 0`.
`EFFECTIVE_DATE_BEFORE_HIRE`	`effectiveDate` precedes the parent job's `hireDate`.
`EFFECTIVE_DATE_BEFORE_MIN`	`effectiveDate` precedes the caller-supplied minimum (typically tomorrow).

Example

import { CompensationErrorCodes } from '@gusto/embedded-react-sdk'

<Fields.Rate
  label="Compensation amount"
  validationMessages={{
    [CompensationErrorCodes.REQUIRED]: 'Amount is required',
    [CompensationErrorCodes.RATE_MINIMUM]: 'Amount must be at least $1.00',
    [CompensationErrorCodes.RATE_EXEMPT_THRESHOLD]: 'Exempt employees must meet the salary threshold',
  }}
/>

Type Declaration

Name	Type
`EFFECTIVE_DATE_BEFORE_HIRE`	`"EFFECTIVE_DATE_BEFORE_HIRE"`
`EFFECTIVE_DATE_BEFORE_MIN`	`"EFFECTIVE_DATE_BEFORE_MIN"`
`PAYMENT_UNIT_COMMISSION`	`"PAYMENT_UNIT_COMMISSION"`
`PAYMENT_UNIT_OWNER`	`"PAYMENT_UNIT_OWNER"`
`RATE_COMMISSION_ZERO`	`"RATE_COMMISSION_ZERO"`
`RATE_EXEMPT_THRESHOLD`	`"RATE_EXEMPT_THRESHOLD"`
`RATE_MINIMUM`	`"RATE_MINIMUM"`
`REQUIRED`	`"REQUIRED"`

CompensationFieldsMetadata

Field	Type
`adjustForMinimumWage`	`FieldMetadata`
`effectiveDate`	`FieldMetadata`
`flsaStatus`	`FieldMetadataWithOptions`<`FlsaStatusType`>
`minimumWageId`	`FieldMetadataWithOptions`<`MinimumWage`>
`paymentUnit`	`FieldMetadataWithOptions`<`PaymentUnit`>
`rate`	`FieldMetadata`
`title`	`FieldMetadata`

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

Remarks

Includes per-field isDisabled, isRequired, and the dynamic option list for select fields (flsaStatus, paymentUnit, minimumWageId). effectiveDate additionally carries minDate / maxDate derived from the parent job's hire date and any pending future compensation.

CompensationFormData

Shape of the form values managed by useCompensationForm.

Remarks

Accepted as defaultValues on useCompensationForm and returned by form.getFormSubmissionValues() once the form has validated. effectiveDate is an ISO date string (YYYY-MM-DD) or null; flsaStatus is optional so the field can render an empty placeholder when nothing is preselected (requiredness is enforced on submit per mode).

Properties

Property	Type	Description
`adjustForMinimumWage`	`boolean`	-
`effectiveDate`	`string` \| `null`	The effective date a new compensation should take effect on. - create mode (`compensationId` absent): required; partners typically default to the parent job's `hireDate` (onboarding stub-fill) or a future date (rate change). Must be on or after `hireDate`. Server-side this maps to POST /v1/jobs/:jobId/compensations. - update mode (`compensationId` present): optional; if omitted the API keeps the existing effective date. The `hireDate` lower bound is not enforced — loaded values may legitimately predate the hire date. Maps to PUT /v1/compensations/:id.
`flsaStatus`	`"Exempt"` \| `"Salaried Nonexempt"` \| `"Nonexempt"` \| `"Owner"` \| `"Commission Only Exempt"` \| `"Commission Only Nonexempt"` \| `undefined`	-
`minimumWageId`	`string`	-
`paymentUnit`	`"Hour"` \| `"Week"` \| `"Month"` \| `"Year"` \| `"Paycheck"`	-
`rate`	`number`	-
`title`	`string`	Optional in both modes. Setting title here scopes the change to this compensation's `effectiveDate` — pair it with a future-dated comp to schedule a promotion title alongside a rate change. Use `useJobForm.Fields.Title` instead when creating a job (title is required by the API on job creation) or when renaming the active role immediately, and avoid rendering both fields on the same screen.

CompensationOptionalFieldsToRequire

CompensationOptionalFieldsToRequire = OptionalFieldsToRequire<typeof requiredFieldsConfig>

Override which fields are required on a given submission mode of useCompensationForm.

Remarks

Each mode key lists the fields that are optional by default for that mode but should be promoted to required. adjustForMinimumWage is always required and minimumWageId is automatically required when adjustForMinimumWage is true — neither is configurable here.

Field	Required on create	Required on update	Configurable?
`flsaStatus`	Yes	No	Yes (on update)
`paymentUnit`	Yes	No	Yes (on update)
`rate`	Yes	No	Yes (on update)
`effectiveDate`	Yes	No	Yes (on update)
`title`	No	No	Yes (either mode)
`adjustForMinimumWage`	Yes	Yes	No
`minimumWageId`	When toggle is on	When toggle is on	No

Example

const compensation = useCompensationForm({
  employeeId,
  jobId,
  compensationId,
  optionalFieldsToRequire: {
    update: ['title', 'rate'],
  },
})

CompensationSubmitOptions

Optional values supplied to useCompensationForm's actions.onSubmit at submit time.

Remarks

Use these to override hook-construction props when an ID isn't known at mount — most commonly the onboarding stub-fill chain, where useJobForm creates the parent job and returns the auto-created stub compensation, and the IDs and version are threaded into this hook's onSubmit to PUT the stub.

Properties

Property	Type	Description
`compensationId?`	`string`	Override compensationId — when present, forces update (PUT) routing regardless of hook construction.
`compensationVersion?`	`string`	Compensation version for optimistic locking on PUT. Required when forcing update routing post-create (e.g. updating the auto-created stub returned from `POST /v1/employees/:id/jobs`). When omitted, the hook reads the version from its cached `currentCompensation`.
`effectiveDate?`	`string`	Supply `effectiveDate` at submit time. When `withEffectiveDateField` is `true`, this overrides the form's value. When `withEffectiveDateField` is `false`, this is the only way to put `effective_date` on the wire — the form value is not read in that mode (matching the options-only convention of `useWorkAddressForm` / `useHomeAddressForm` / `useJobForm`).
`jobId?`	`string`	Override jobId — required when creating a compensation if not configured at hook construction (e.g. when the parent job was just created in the same submit chain).

Endpoints

Method	Path
PUT	`/v1/compensations/:compensationId`
GET	`/v1/employees/:employeeId`
GET	`/v1/employees/:employeeId/jobs`
GET	`/v1/employees/:employeeId/work_addresses`
POST	`/v1/jobs/:jobId/compensations`
GET	`/v1/locations/:locationUuid/minimum_wages`

Remarks​

Example​

Props​

UseCompensationFormProps​

Returns​

UseCompensationFormResult​

Remarks​

UseCompensationFormReady​

Fields​

CompensationFormFields​

AdjustForMinimumWage​

AdjustForMinimumWageFieldProps​

EffectiveDate​

CompensationEffectiveDateFieldProps​

FlsaStatus​

FlsaStatusFieldProps​

MinimumWageId​

MinimumWageIdFieldProps​

PaymentUnit​

PaymentUnitFieldProps​

Rate​

RateFieldProps​

Title​

CompensationTitleFieldProps​

Validations​

CompensationEffectiveDateValidation​

Remarks​

CompensationRequiredValidation​

Remarks​

RateValidation​

Remarks​

Utility types​

CompensationErrorCode​

CompensationErrorCodes​

Remarks​

Example​

Type Declaration​

CompensationFieldsMetadata​

Remarks​

CompensationFormData​

Remarks​

Properties​

CompensationOptionalFieldsToRequire​

Remarks​

Example​

CompensationSubmitOptions​

Remarks​

Properties​

Endpoints​

Remarks

Example

Props

UseCompensationFormProps

Returns

UseCompensationFormResult

Remarks

UseCompensationFormReady

Fields

CompensationFormFields

AdjustForMinimumWage

AdjustForMinimumWageFieldProps

EffectiveDate

CompensationEffectiveDateFieldProps

FlsaStatus

FlsaStatusFieldProps

MinimumWageId

MinimumWageIdFieldProps

PaymentUnit

PaymentUnitFieldProps

Rate

RateFieldProps

Title

CompensationTitleFieldProps

Validations

CompensationEffectiveDateValidation

Remarks

CompensationRequiredValidation

Remarks

RateValidation

Remarks

Utility types

CompensationErrorCode

CompensationErrorCodes

Remarks

Example

Type Declaration

CompensationFieldsMetadata

Remarks

CompensationFormData

Remarks

Properties

CompensationOptionalFieldsToRequire

Remarks

Example

CompensationSubmitOptions

Remarks

Properties

Endpoints