useBankForm

useBankForm(props: UseBankFormProps): HookLoadingResult | UseBankFormReady

Headless React Hook Form hook for creating an employee bank account.

Remarks

Captures the account nickname, routing number, account number, and account type. Creating a bank account also updates the employee's payment method on the Gusto API. Returns the standard HookLoadingResult | UseBankFormReady discriminated union; in practice the hook transitions to the ready state immediately because it does not fetch any server data.

Example

Example

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

function AddBankAccount({ employeeId }: { employeeId: string }) {
  const bankForm = useBankForm({ employeeId })

  if (bankForm.isLoading) return null
  const { Fields } = bankForm.form

  return (
    <SDKFormProvider formHookResult={bankForm}>
      <form
        onSubmit={e => {
          e.preventDefault()
          void bankForm.actions.onSubmit()
        }}
      >
        <Fields.Name label="Account nickname" />
        <Fields.RoutingNumber label="Routing number" />
        <Fields.AccountNumber label="Account number" />
        <Fields.AccountType label="Account type" />
        <button type="submit" disabled={bankForm.status.isPending}>Save</button>
      </form>
    </SDKFormProvider>
  )
}

Props

UseBankFormProps

Props for useBankForm.

Property	Type	Description
defaultValues?	Partial<BankFormData>	Pre-fill form values. accountType defaults to 'Checking' when not supplied.
employeeId?	string	Employee for whom to create the bank account. May be supplied later via BankFormSubmitOptions.employeeId.
optionalFieldsToRequire?	BankFormOptionalFieldsToRequire	Override optional fields to be required. Reserved for future schema expansion — every field is required by default.
shouldFocusError?	boolean	Auto-focus the first invalid field on submit. Set to false when using composeSubmitHandler. Defaults to true.
validationMode?	"onChange" | "onBlur" | "onSubmit" | "onTouched" | "all"	When validation runs. Passed through to react-hook-form. Defaults to 'onSubmit'.

Returns

HookLoadingResult | UseBankFormReady

A loading-state result while the hook is initializing, or a UseBankFormReady ready to render.

UseBankFormResult

UseBankFormResult = HookLoadingResult | UseBankFormReady

Return type of useBankForm — a discriminated union on isLoading.

---

UseBankFormReady

Ready-state return value of useBankForm.

Property	Type	Description
actions	object	Submit the form. Optional BankFormSubmitOptions can override the employeeId supplied to the hook.
actions.onSubmit	(options?: BankFormSubmitOptions) => Promise<HookSubmitResult<EmployeeBankAccount> | undefined>	-
data	Record<string, never>	No server-fetched data — the create form derives everything from user input.
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	BankFormFields	-
form.fieldsMetadata	BankFormFieldsMetadata	-
form.getFormSubmissionValues	() => BankFormData | undefined	-
form.hookFormInternals	HookFormInternals<BankFormData>	-
isLoading	false	Always false in this branch; discriminates from HookLoadingResult.
status	object	isPending reflects the in-flight create mutation; mode is always 'create'.
status.isPending	boolean	-
status.mode	"create"	-

Fields

BankFormFields

Field components exposed by useBankForm on form.Fields.

Property	Type	Description
AccountNumber	ComponentType<AccountNumberFieldProps>	Bound to accountNumber.
AccountType	ComponentType<AccountTypeFieldProps>	Bound to accountType.
Name	ComponentType<NameFieldProps>	Bound to name.
RoutingNumber	ComponentType<RoutingNumberFieldProps>	Bound to routingNumber.

---

AccountNumber

Bound to accountNumber.

<form.Fields.AccountNumber
  label="Account number"
  validationMessages={{ REQUIRED: '…', INVALID_ACCOUNT_NUMBER: '…' }}
/>

AccountNumberFieldProps

HookFieldProps<TextInputHookFieldProps<AccountNumberValidation>>

Props accepted by useBankForm's Fields.AccountNumber 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<AccountNumberValidation>	Custom error text keyed by validation error code.

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

---

AccountType

Bound to accountType.

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

AccountTypeFieldProps

HookFieldProps<RadioGroupHookFieldProps<BankFormRequiredValidation, AccountType>>

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

Also accepts description, formHookResult from RadioGroupHookFieldProps.

---

Name

Bound to name.

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

NameFieldProps

HookFieldProps<TextInputHookFieldProps<BankFormRequiredValidation>>

Props accepted by useBankForm's Fields.Name 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<BankFormRequiredValidation>	Custom error text keyed by validation error code.

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

---

RoutingNumber

Bound to routingNumber.

<form.Fields.RoutingNumber
  label="Routing number"
  validationMessages={{ REQUIRED: '…', INVALID_ROUTING_NUMBER: '…' }}
/>

RoutingNumberFieldProps

HookFieldProps<TextInputHookFieldProps<RoutingNumberValidation>>

Props accepted by useBankForm's Fields.RoutingNumber 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<RoutingNumberValidation>	Custom error text keyed by validation error code.

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

Validations

AccountNumberValidation

AccountNumberValidation = "REQUIRED" | "INVALID_ACCOUNT_NUMBER"

Validation error codes emitted by the accountNumber field of useBankForm.

---

BankFormRequiredValidation

BankFormRequiredValidation = "REQUIRED"

Validation error codes emitted by useBankForm fields that only emit REQUIRED.

---

RoutingNumberValidation

RoutingNumberValidation = "REQUIRED" | "INVALID_ROUTING_NUMBER"

Validation error codes emitted by the routingNumber field of useBankForm.

Utility types

ACCOUNT_TYPES

const ACCOUNT_TYPES: readonly ["Checking", "Savings"]

Supported bank account type values: checking and savings.

---

AccountType

AccountType = "Checking" | "Savings"

Union of bank account type values that the form accepts.

---

BankFormData

Shape of the values managed by the bank account form.

Properties

Property	Type
accountNumber	string
accountType	"Checking" | "Savings"
name	string
routingNumber	string

---

BankFormErrorCode

BankFormErrorCode = "REQUIRED" | "INVALID_ROUTING_NUMBER" | "INVALID_ACCOUNT_NUMBER"

Union of validation error code strings emitted by the bank account form schema.

---

BankFormErrorCodes

const BankFormErrorCodes: object

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

Type Declaration

Name	Type
INVALID_ACCOUNT_NUMBER	"INVALID_ACCOUNT_NUMBER"
INVALID_ROUTING_NUMBER	"INVALID_ROUTING_NUMBER"
REQUIRED	"REQUIRED"

---

BankFormField

BankFormField = "routingNumber" | "accountNumber" | "name" | "accountType"

Field names accepted by the bank account form.

---

BankFormFieldsMetadata

Field	Type
accountNumber	FieldMetadata
accountType	FieldMetadataWithOptions<"Checking" | "Savings">
name	FieldMetadata
routingNumber	FieldMetadata

Per-field metadata exposed on form.fieldsMetadata for useBankForm.

---

BankFormOptionalFieldsToRequire

BankFormOptionalFieldsToRequire = OptionalFieldsToRequire<typeof requiredFieldsConfig>

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

---

BankFormSubmitOptions

Optional submit-time overrides for useBankForm's onSubmit.

Properties

Property	Type	Description
employeeId?	string	Override the employeeId configured at hook construction. Useful when the employee is created in the same submit chain.

---

Endpoints

Method	Path
POST	/v1/employees/:employeeId/bank_accounts