usePayScheduleForm

usePayScheduleForm(props: UsePayScheduleFormProps): HookLoadingResult | UsePayScheduleFormReady

Form hook for creating or updating a company pay schedule.

Remarks

When payScheduleId is supplied the hook loads that schedule and issues an update on submit; when omitted it operates in create mode. While both anchor date fields are filled in, the hook fetches a live pay period calendar preview exposed on data.payPeriodPreview. data.paymentSpeedDays reflects the company's payment configuration and is useful for surfacing UI hints about how far ahead the first pay date must be.

Example

Example

import {
  usePayScheduleForm,
  SDKFormProvider,
  type UsePayScheduleFormReady,
} from '@gusto/embedded-react-sdk'

function PaySchedulePage({ companyId }: { companyId: string }) {
  const paySchedule = usePayScheduleForm({ companyId })

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

  return <PayScheduleFormReady paySchedule={paySchedule} />
}

function PayScheduleFormReady({ paySchedule }: { paySchedule: UsePayScheduleFormReady }) {
  const { Fields } = paySchedule.form

  return (
    <SDKFormProvider formHookResult={paySchedule}>
      <form
        onSubmit={e => {
          e.preventDefault()
          void paySchedule.actions.onSubmit()
        }}
      >
        <Fields.CustomName label="Name" validationMessages={{ REQUIRED: 'Name is required' }} />
        <Fields.Frequency label="Frequency" validationMessages={{ REQUIRED: 'Frequency is required' }} />
        {Fields.CustomTwicePerMonth && <Fields.CustomTwicePerMonth label="Frequency Options" />}
        <Fields.AnchorPayDate label="First pay date" validationMessages={{ REQUIRED: 'Required' }} />
        <Fields.AnchorEndOfPayPeriod label="First pay period end" validationMessages={{ REQUIRED: 'Required' }} />
        {Fields.Day1 && (
          <Fields.Day1
            label="First pay day of the month"
            validationMessages={{ REQUIRED: 'Required', DAY_RANGE: 'Must be 1–31' }}
          />
        )}
        {Fields.Day2 && (
          <Fields.Day2
            label="Last pay day of the month"
            validationMessages={{ REQUIRED: 'Required', DAY_RANGE: 'Must be 1–31' }}
          />
        )}
        <button type="submit" disabled={paySchedule.status.isPending}>Save</button>
      </form>
    </SDKFormProvider>
  )
}

Props

UsePayScheduleFormProps

Configuration options for usePayScheduleForm.

Remarks

Presence or absence of payScheduleId selects between update and create mode.

Property	Type	Description
companyId	string	UUID of the company that owns the pay schedule.
defaultValues?	Partial<PayScheduleFormData>	Pre-fill form values. Server data takes precedence on update.
optionalFieldsToRequire?	PayScheduleOptionalFieldsToRequire	Override fields that are optional on a given mode to be required. See PayScheduleOptionalFieldsToRequire.
payScheduleId?	string	When set, loads that pay schedule and updates it on submit. When omitted, the form is in create mode and creates a new schedule on submit.
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

HookLoadingResult | UsePayScheduleFormReady

A HookLoadingResult while loading, or a UsePayScheduleFormReady once ready.

UsePayScheduleFormResult

UsePayScheduleFormResult = HookLoadingResult | UsePayScheduleFormReady

Discriminated union returned by usePayScheduleForm.

---

UsePayScheduleFormReady

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

Remarks

Discriminated by isLoading: false. Extends BaseFormHookReady with the pay-schedule-specific data, status, actions, and form.Fields shape.

Property	Type	Description
actions	object	Available actions.
actions.onSubmit	() => Promise<HookSubmitResult<PayScheduleShow> | undefined>	Validates the form and dispatches the create or update mutation. Returns the saved schedule, or undefined if validation failed.
data	object	Static entity data resolved from the API.
data.paymentSpeedDays	number | null	Business days the company needs to process payroll, derived from payment configs; null if unavailable.
data.payPeriodPreview	PaySchedulePreviewPayPeriod[] | null	Upcoming pay periods previewed from current form values; null until the anchor date fields are complete.
data.payPreviewLoading	boolean	true while the pay period preview request is in flight.
data.paySchedule	PayScheduleShow | null	The pay schedule 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	PayScheduleFormFields	-
form.fieldsMetadata	PayScheduleFieldsMetadata	-
form.getFormSubmissionValues	() => PayScheduleFormData | undefined	-
form.hookFormInternals	HookFormInternals<PayScheduleFormData>	-
isLoading	false	Always false in this branch; discriminates from HookLoadingResult.
status	object	Reactive status flags.
status.isPending	boolean	true while the create or update mutation is in flight.
status.mode	"create" | "update"	Whether the form is creating a new schedule or updating an existing one.

Fields

PayScheduleFormFields

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

Remarks

CustomTwicePerMonth, Day1, and Day2 are conditionally undefined based on the selected frequency and twice-per-month strategy — always null-check them before rendering.

Property	Type	Description
AnchorEndOfPayPeriod	ComponentType<AnchorEndOfPayPeriodFieldProps>	Bound to anchorEndOfPayPeriod. First pay period end date picker. Always available.
AnchorPayDate	ComponentType<AnchorPayDateFieldProps>	Bound to anchorPayDate. First pay date picker. Always available.
CustomName	ComponentType<CustomNameFieldProps>	Bound to customName. Display name text input. Always available.
Frequency	ComponentType<FrequencyFieldProps>	Bound to frequency. Frequency selector. Always available.
CustomTwicePerMonth	ComponentType<CustomTwicePerMonthFieldProps> | undefined	Bound to customTwicePerMonth. Twice-per-month strategy radio group. Only available when frequency is 'Twice per month'.
Day1	ComponentType<Day1FieldProps> | undefined	Bound to day1. First-pay-day-of-month number input. Available when frequency is 'Monthly', or 'Twice per month' with 'custom' strategy.
Day2	ComponentType<Day2FieldProps> | undefined	Bound to day2. Last-pay-day-of-month number input. Available when frequency is 'Twice per month' with 'custom' strategy.

---

AnchorEndOfPayPeriod

Bound to anchorEndOfPayPeriod. First pay period end date picker. Always available.

<form.Fields.AnchorEndOfPayPeriod
  label="Anchor end of pay period"
  validationMessages={{ REQUIRED: '…' }}
/>

AnchorEndOfPayPeriodFieldProps

HookFieldProps<DatePickerHookFieldProps<PayScheduleRequiredValidation>>

Props accepted by usePayScheduleForm's Fields.AnchorEndOfPayPeriod 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<PayScheduleRequiredValidation>	Custom error text keyed by validation error code.

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

---

AnchorPayDate

Bound to anchorPayDate. First pay date picker. Always available.

<form.Fields.AnchorPayDate
  label="Anchor pay date"
  validationMessages={{ REQUIRED: '…' }}
/>

AnchorPayDateFieldProps

HookFieldProps<DatePickerHookFieldProps<PayScheduleRequiredValidation>>

Props accepted by usePayScheduleForm's Fields.AnchorPayDate 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<PayScheduleRequiredValidation>	Custom error text keyed by validation error code.

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

---

CustomName

Bound to customName. Display name text input. Always available.

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

CustomNameFieldProps

HookFieldProps<TextInputHookFieldProps<PayScheduleRequiredValidation>>

Props accepted by usePayScheduleForm's Fields.CustomName 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<PayScheduleRequiredValidation>	Custom error text keyed by validation error code.

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

---

CustomTwicePerMonth

Bound to customTwicePerMonth. Twice-per-month strategy radio group. Only available when frequency is 'Twice per month'.

{form.Fields.CustomTwicePerMonth && (
  <form.Fields.CustomTwicePerMonth label="Custom twice per month" />
)}

CustomTwicePerMonthFieldProps

HookFieldProps<RadioGroupHookFieldProps<never, string>>

Props accepted by usePayScheduleForm's Fields.CustomTwicePerMonth 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: string) => 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.

---

Day1

Bound to day1. First-pay-day-of-month number input. Available when frequency is 'Monthly', or 'Twice per month' with 'custom' strategy.

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

Day1FieldProps

HookFieldProps<NumberInputHookFieldProps<DayValidation>>

Props accepted by usePayScheduleForm's Fields.Day1 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<DayValidation>	Custom error text keyed by validation error code.

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

---

Day2

Bound to day2. Last-pay-day-of-month number input. Available when frequency is 'Twice per month' with 'custom' strategy.

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

Day2FieldProps

HookFieldProps<NumberInputHookFieldProps<DayValidation>>

Props accepted by usePayScheduleForm's Fields.Day2 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<DayValidation>	Custom error text keyed by validation error code.

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

---

Frequency

Bound to frequency. Frequency selector. Always available.

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

FrequencyFieldProps

HookFieldProps<SelectHookFieldProps<PayScheduleRequiredValidation, PayScheduleFrequency>>

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

Also accepts description, formHookResult, portalContainer from SelectHookFieldProps.

Validations

DayValidation

DayValidation = "REQUIRED" | "DAY_RANGE"

Validation error codes emitted by the day1 and day2 fields of usePayScheduleForm.

Remarks

Use these as keys in validationMessages on Fields.Day1 and Fields.Day2. See PayScheduleErrorCodes.

---

PayScheduleRequiredValidation

PayScheduleRequiredValidation = "REQUIRED"

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

Remarks

Used as the validationMessages key for the custom name, frequency, anchor pay date, and anchor end-of-pay-period fields. See PayScheduleErrorCodes.

Utility types

PayScheduleErrorCode

PayScheduleErrorCode = "REQUIRED" | "DAY_RANGE"

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

---

PayScheduleErrorCodes

const PayScheduleErrorCodes: object

Validation error codes emitted by usePayScheduleForm fields.

Remarks

Use these as validationMessages keys on the corresponding Fields.* components.

Type Declaration

Name	Type
DAY_RANGE	"DAY_RANGE"
REQUIRED	"REQUIRED"

---

PayScheduleField

PayScheduleField = "frequency" | "anchorPayDate" | "anchorEndOfPayPeriod" | "day1" | "day2" | "customName" | "customTwicePerMonth"

Union of field names managed by the pay schedule form.

---

PayScheduleFieldsMetadata

Field	Type
anchorEndOfPayPeriod	FieldMetadata
anchorPayDate	FieldMetadata
customName	FieldMetadata
customTwicePerMonth	FieldMetadataWithOptions<string>
day1	FieldMetadata
day2	FieldMetadata
frequency	FieldMetadataWithOptions<"Every week" | "Every other week" | "Twice per month" | "Monthly">

Type of form.fieldsMetadata returned by usePayScheduleForm.

---

PayScheduleFormData

Shape of the values managed by the pay schedule form.

Properties

Property	Type
anchorEndOfPayPeriod	string | null
anchorPayDate	string | null
customName	string
customTwicePerMonth	string
day1	number
day2	number
frequency	"Every week" | "Every other week" | "Twice per month" | "Monthly"

---

PayScheduleFrequency

PayScheduleFrequency = "Every week" | "Every other week" | "Twice per month" | "Monthly"

Pay schedule frequency values accepted by usePayScheduleForm.

---

PayScheduleOptionalFieldsToRequire

PayScheduleOptionalFieldsToRequire = OptionalFieldsToRequire<typeof requiredFieldsConfig>

Configuration for promoting optional pay schedule fields to required in a given mode.

Remarks

Only fields that are optional by default can be promoted. Currently customTwicePerMonth is the only configurable field.

Endpoints

Method	Path
POST	/v1/companies/:companyId/pay_schedules
GET	/v1/companies/:companyId/pay_schedules/:payScheduleId
PUT	/v1/companies/:companyId/pay_schedules/:payScheduleId
GET	/v1/companies/:companyId/pay_schedules/preview
GET	/v1/companies/:companyUuid/payment_configs