useEmployeeDetailsForm

useEmployeeDetailsForm(input: UseEmployeeDetailsFormProps): HookLoadingResult | UseEmployeeDetailsFormReady

Headless hook for creating or updating an employee's profile details — name, email, SSN, date of birth, and self-onboarding preference.

Remarks

Returns a discriminated union: a loading variant while the underlying employee fetch resolves, and a ready variant exposing the form's data, pending status, submit action, error handling, and bound Fields. Self-onboarding is only toggleable when the employee's onboarding status allows it; otherwise form.Fields.SelfOnboarding is undefined.

Example

Example

import {
  useEmployeeDetailsForm,
  SDKFormProvider,
  type UseEmployeeDetailsFormReady,
} from '@gusto/embedded-react-sdk'

function EmployeeDetailsPage({ companyId, employeeId }: { companyId: string; employeeId?: string }) {
  const employeeDetails = useEmployeeDetailsForm({ companyId, employeeId })

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

  return <EmployeeDetailsReady employeeDetails={employeeDetails} />
}

function EmployeeDetailsReady({ employeeDetails }: { employeeDetails: UseEmployeeDetailsFormReady }) {
  const { Fields } = employeeDetails.form

  const handleSubmit = async () => {
    await employeeDetails.actions.onSubmit({
      onEmployeeCreated: emp => console.log('Created:', emp.uuid),
      onEmployeeUpdated: emp => console.log('Updated:', emp.uuid),
    })
  }

  return (
    <SDKFormProvider formHookResult={employeeDetails}>
      <form onSubmit={e => { e.preventDefault(); void handleSubmit() }}>
        <Fields.FirstName label="First name" />
        <Fields.LastName label="Last name" />
        <Fields.Email label="Personal email" />
        <Fields.DateOfBirth label="Date of birth" />
        <Fields.Ssn label="Social Security number" />
        <button type="submit" disabled={employeeDetails.status.isPending}>Save</button>
      </form>
    </SDKFormProvider>
  )
}

Props

UseEmployeeDetailsFormProps

Options for useEmployeeDetailsForm.

Remarks

Discriminated by mode: in create mode supply companyId and omit employeeId; in update mode supply employeeId (and optionally companyId).

Shared options — apply to every variant.

Property	Type	Description
defaultValues?	Partial<EmployeeDetailsFormData>	Initial values applied before any employee data loads.
optionalFieldsToRequire?	EmployeeDetailsOptionalFieldsToRequire	Fields that are optional by default but should be promoted to required for this form instance.
shouldFocusError?	boolean	Whether react-hook-form should focus the first error on validation failure. Defaults to true.
validationMode?	UseFormProps["mode"]	When validation runs. Forwarded to react-hook-form's mode. Defaults to 'onSubmit'.
withSelfOnboardingField?	boolean	Whether to expose the self-onboarding toggle as form.Fields.SelfOnboarding. Defaults to true.

Supply the fields for exactly one of the following variants:

Variant 1

Property	Type
companyId	string
employeeId?	never

Variant 2

Property	Type
employeeId	string
companyId?	string

Returns

HookLoadingResult | UseEmployeeDetailsFormReady

A HookLoadingResult while loading, or a UseEmployeeDetailsFormReady once ready.

UseEmployeeDetailsFormResult

UseEmployeeDetailsFormResult = HookLoadingResult | UseEmployeeDetailsFormReady

Return type of useEmployeeDetailsForm.

---

UseEmployeeDetailsFormReady

The ready-state result returned by useEmployeeDetailsForm once data has loaded.

Remarks

Provides the form's data snapshot, pending status, submit actions, error handling, and the form.Fields map.

Property	Type	Description
actions	object	Submit and related actions.
actions.onSubmit	(callbacks?: EmployeeDetailsSubmitCallbacks) => Promise<HookSubmitResult<Employee> | undefined>	Validates the form and submits the changes. Returns the created or updated employee, or undefined when validation fails.
data	object	The loaded employee data, or null in create mode.
data.employee	Employee | null	The employee being edited, or 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	EmployeeDetailsFormFields	-
form.fieldsMetadata	EmployeeDetailsFieldsMetadata	-
form.getFormSubmissionValues	() => EmployeeDetailsFormData | undefined	-
form.hookFormInternals	HookFormInternals<EmployeeDetailsFormData>	-
isLoading	false	Always false in this branch; discriminates from HookLoadingResult.
status	object	Submit status and form mode.
status.isPending	boolean	true while the create, update, or onboarding-status mutation is in flight.
status.mode	"create" | "update"	'create' when no employeeId was supplied, 'update' otherwise.

Fields

EmployeeDetailsFormFields

The Field components exposed by useEmployeeDetailsForm as form.Fields.

Remarks

Each entry is a component bound to a specific form field. SelfOnboarding may be undefined when the field is not toggleable.

Property	Type	Description
DateOfBirth	ComponentType<DateOfBirthFieldProps>	Bound to dateOfBirth. Date picker.
Email	ComponentType<EmailFieldProps>	Bound to email. Text input.
FirstName	ComponentType<FirstNameFieldProps>	Bound to firstName. Text input.
LastName	ComponentType<LastNameFieldProps>	Bound to lastName. Text input.
MiddleInitial	ComponentType<MiddleInitialFieldProps>	Bound to middleInitial. Text input.
Ssn	ComponentType<SsnFieldProps>	Bound to ssn. Text input.
SelfOnboarding	ComponentType<SelfOnboardingFieldProps> | undefined	Bound to selfOnboarding. Switch, or undefined when the field is not toggleable.

---

DateOfBirth

Bound to dateOfBirth. Date picker.

<form.Fields.DateOfBirth
  label="Date of birth"
  validationMessages={{ REQUIRED: '…' }}
/>

DateOfBirthFieldProps

HookFieldProps<DatePickerHookFieldProps<EmployeeDetailsRequiredValidation>>

Props accepted by useEmployeeDetailsForm's Fields.DateOfBirth 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<EmployeeDetailsRequiredValidation>	Custom error text keyed by validation error code.

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

---

Email

Bound to email. Text input.

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

EmailFieldProps

HookFieldProps<TextInputHookFieldProps<EmailValidation>>

Props accepted by useEmployeeDetailsForm's Fields.Email 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<EmailValidation>	Custom error text keyed by validation error code.

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

---

FirstName

Bound to firstName. Text input.

<form.Fields.FirstName
  label="First name"
  validationMessages={{ REQUIRED: '…', INVALID_NAME: '…' }}
/>

FirstNameFieldProps

HookFieldProps<TextInputHookFieldProps<NameValidation>>

Props accepted by useEmployeeDetailsForm's Fields.FirstName 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<NameValidation>	Custom error text keyed by validation error code.

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

---

LastName

Bound to lastName. Text input.

<form.Fields.LastName
  label="Last name"
  validationMessages={{ REQUIRED: '…', INVALID_NAME: '…' }}
/>

LastNameFieldProps

HookFieldProps<TextInputHookFieldProps<NameValidation>>

Props accepted by useEmployeeDetailsForm's Fields.LastName 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<NameValidation>	Custom error text keyed by validation error code.

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

---

MiddleInitial

Bound to middleInitial. Text input.

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

MiddleInitialFieldProps

HookFieldProps<TextInputHookFieldProps<EmployeeDetailsRequiredValidation>>

Props accepted by useEmployeeDetailsForm's Fields.MiddleInitial 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<EmployeeDetailsRequiredValidation>	Custom error text keyed by validation error code.

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

---

SelfOnboarding

Bound to selfOnboarding. Switch, or undefined when the field is not toggleable.

{form.Fields.SelfOnboarding && (
  <form.Fields.SelfOnboarding label="Self onboarding" />
)}

SelfOnboardingFieldProps

HookFieldProps<SwitchHookFieldProps>

Props accepted by useEmployeeDetailsForm's Fields.SelfOnboarding component.

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

Also accepts description, formHookResult from SwitchHookFieldProps.

---

Ssn

Bound to ssn. Text input.

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

SsnFieldProps

HookFieldProps<TextInputHookFieldProps<SsnValidation, SsnRequiredValidation>>

Props accepted by useEmployeeDetailsForm's Fields.Ssn 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<SsnValidation, SsnRequiredValidation>	Custom error text keyed by validation error code.

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

Validations

EmailValidation

EmailValidation = "REQUIRED" | "INVALID_EMAIL"

Validation error codes emitted by the email field of useEmployeeDetailsForm.

Remarks

Use these as keys in validationMessages on Fields.Email. The REQUIRED code fires when the email is empty and required — either because self-onboarding is enabled or because the field was promoted via optionalFieldsToRequire. See EmployeeDetailsErrorCodes.

---

EmployeeDetailsRequiredValidation

EmployeeDetailsRequiredValidation = "REQUIRED"

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

Remarks

Used as the validationMessages key for the middle initial and date of birth fields. See EmployeeDetailsErrorCodes.

---

NameValidation

NameValidation = "REQUIRED" | "INVALID_NAME"

Validation error codes emitted by the name fields of useEmployeeDetailsForm.

Remarks

Use these as keys in validationMessages on Fields.FirstName and Fields.LastName. See EmployeeDetailsErrorCodes for the full description of each code.

---

SsnRequiredValidation

SsnRequiredValidation = "REQUIRED"

The required-field error code for the ssn field of useEmployeeDetailsForm.

Remarks

The required rule is automatically waived when the employee already has an SSN on file, even if ssn is included in optionalFieldsToRequire.

---

SsnValidation

SsnValidation = "INVALID_SSN"

The format-validation error code emitted by the ssn field of useEmployeeDetailsForm.

Remarks

Use as a key in validationMessages on Fields.Ssn. See EmployeeDetailsErrorCodes.

Utility types

EmployeeDetailsSubmitCallbacks

Optional callbacks passed to onSubmit.

Remarks

Only the callback matching the submit mode fires — onEmployeeCreated on create, onEmployeeUpdated on update. onOnboardingStatusUpdated fires when toggling the self-onboarding switch changes the employee's onboarding status as part of an update.

Properties

Property	Type	Description
onEmployeeCreated?	(employee: Employee) => void	Fired after a new employee is successfully created.
onEmployeeUpdated?	(employee: Employee) => void	Fired after an existing employee is successfully updated.
onOnboardingStatusUpdated?	(status: unknown) => void	Fired when an update toggles self-onboarding and the employee's onboarding status changes.

---

EmployeeDetailsErrorCode

EmployeeDetailsErrorCode = "REQUIRED" | "INVALID_NAME" | "INVALID_EMAIL" | "INVALID_SSN"

Union of validation error code strings emitted by the employee details form schema.

---

EmployeeDetailsErrorCodes

const EmployeeDetailsErrorCodes: object

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

Type Declaration

Name	Type
INVALID_EMAIL	"INVALID_EMAIL"
INVALID_NAME	"INVALID_NAME"
INVALID_SSN	"INVALID_SSN"
REQUIRED	"REQUIRED"

---

EmployeeDetailsField

EmployeeDetailsField = Exclude<keyof typeof fieldValidators, "selfOnboarding">

Field names accepted by the employee details form.

---

EmployeeDetailsFieldsMetadata

Field	Type
dateOfBirth	FieldMetadata
email	FieldMetadata
firstName	FieldMetadata
lastName	FieldMetadata
middleInitial	FieldMetadata
selfOnboarding	FieldMetadata
ssn	FieldMetadata

Shape of form.fieldsMetadata returned by useEmployeeDetailsForm.

---

EmployeeDetailsFormData

Shape of the values managed by the employee details form.

Properties

Property	Type
dateOfBirth	string
email	string
firstName	string
lastName	string
middleInitial	string
selfOnboarding	boolean
ssn	string

---

EmployeeDetailsOptionalFieldsToRequire

EmployeeDetailsOptionalFieldsToRequire = OptionalFieldsToRequire<typeof requiredFieldsConfig>

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

---

Endpoints

Method	Path
POST	/v1/companies/:companyId/employees
GET	/v1/employees/:employeeId
PUT	/v1/employees/:employeeId
PUT	/v1/employees/:employeeId/onboarding_status