useSignEmployeeForm

useSignEmployeeForm(props: UseSignEmployeeFormProps): HookLoadingResult | UseSignEmployeeFormReady

Headless hook for signing an employee form — captures a typed signature, electronic consent, and (for I-9 forms) preparer/translator certification.

Remarks

The hook fetches the form metadata and PDF, then exposes the BaseFormHookReady contract with Fields, fieldsMetadata, onSubmit, and error handling. The hook inspects the form's name to detect I-9 forms; when the form is an I-9, Fields.UsedPreparer and the Fields.Preparer1–Preparer4 field groups become defined, along with actions.addPreparer / actions.removePreparer and form.preparers state. Selecting usedPreparer: 'yes' automatically reveals the first preparer section; switching back to 'no' removes all preparer sections and unregisters their fields.

Unlike the CRUD-oriented form hooks (useEmployeeDetailsForm, useCompensationForm, useWorkAddressForm), this hook does not accept defaultValues, requiredFields, or validationMode — the form shape is fixed and all fields except preparer street-2 are required.

Example

Example

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

function SignFormPage({ employeeId, formId }: { employeeId: string; formId: string }) {
  const signForm = useSignEmployeeForm({ employeeId, formId })

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

  const { Fields } = signForm.form

  return (
    <SDKFormProvider formHookResult={signForm}>
      <form
        onSubmit={e => {
          e.preventDefault()
          void signForm.actions.onSubmit()
        }}
      >
        <Fields.Signature
          label="Signature"
          description="Type your full, legal name."
          validationMessages={{ REQUIRED: 'Signature is required' }}
        />
        <Fields.ConfirmSignature
          label="I agree to sign electronically"
          validationMessages={{ REQUIRED: 'You must agree to sign electronically' }}
        />
        <button type="submit" disabled={signForm.status.isPending}>
          Sign form
        </button>
      </form>
    </SDKFormProvider>
  )
}

Props

UseSignEmployeeFormProps

Props for useSignEmployeeForm.

Property	Type	Description
employeeId	string	The associated employee identifier.
formId	string	The UUID of the employee form to sign.

Returns

HookLoadingResult | UseSignEmployeeFormReady

A HookLoadingResult while loading, or a UseSignEmployeeFormReady once the form is loaded.

UseSignEmployeeFormResult

UseSignEmployeeFormResult = HookLoadingResult | UseSignEmployeeFormReady

Result of useSignEmployeeForm — a discriminated union on isLoading.

---

UseSignEmployeeFormReady

Ready-state shape returned by useSignEmployeeForm once the form metadata and PDF have loaded.

Property	Type	Description
actions	object	Imperative actions exposed by the hook.
actions.onSubmit	() => Promise<HookSubmitResult<Form> | undefined>	Validates the form and submits the signature. Resolves with the signed form on success.
actions.addPreparer?	() => void	Adds an additional preparer/translator section (up to 4). Defined only for I-9 forms.
actions.removePreparer?	() => void	Removes the last preparer/translator section and unregisters its fields. Defined only for I-9 forms.
data	object	Loaded data — the form entity and a preview PDF URL.
data.form	Form	The employee form entity fetched from the API (includes uuid, name, title).
data.pdfUrl	string | null | undefined	URL to the form's signed PDF for preview, or undefined while it is still being generated.
errorHandling	HookErrorHandling	Error state and recovery actions.
form	object & object	Form bindings — Fields, fieldsMetadata, and I-9 preparer state.
isLoading	false	Always false in this branch; discriminates from HookLoadingResult.
status	object	Submit-state flags.
status.isPending	boolean	true while the sign mutation is in flight.
status.mode	"create"	Always 'create'; the hook always submits as a signing operation.

Fields

SignEmployeeFormFields

Field components exposed by useSignEmployeeForm on form.Fields.

Remarks

Signature and ConfirmSignature are always present. UsedPreparer and the Preparer1–Preparer4 field groups are only defined when the form being signed is an I-9 and the preparer count has reached that index — always null-check before rendering.

Property	Type	Description
ConfirmSignature	ComponentType<ConfirmSignatureFieldProps>	Bound to confirmSignature. Checkbox for the employee's electronic-signature consent; always present.
Signature	ComponentType<SignatureFieldProps>	Bound to signature. Text input for the employee's typed signature; always present.
Preparer1	PreparerFieldGroup | undefined	First preparer field group; defined only for I-9 forms when preparers.count >= 1.
Preparer2	PreparerFieldGroup | undefined	Second preparer field group; defined only for I-9 forms when preparers.count >= 2.
Preparer3	PreparerFieldGroup | undefined	Third preparer field group; defined only for I-9 forms when preparers.count >= 3.
Preparer4	PreparerFieldGroup | undefined	Fourth preparer field group; defined only for I-9 forms when preparers.count >= 4.
UsedPreparer	ComponentType<UsedPreparerFieldProps> | undefined	Bound to usedPreparer. Radio group asking whether a preparer/translator assisted; defined only for I-9 forms.

---

ConfirmSignature

Bound to confirmSignature. Checkbox for the employee's electronic-signature consent; always present.

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

SignEmployeeFormConfirmSignatureFieldProps

HookFieldProps<CheckboxHookFieldProps<SignEmployeeFormRequiredValidation>>

Props accepted by useSignEmployeeForm's Fields.ConfirmSignature 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.
validationMessages?	ValidationMessages<SignEmployeeFormRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult from CheckboxHookFieldProps.

---

Preparer1

First preparer field group; defined only for I-9 forms when preparers.count >= 1.

{form.Fields.Preparer1 && (
  <>
    <form.Fields.Preparer1.City
      label="City"
      validationMessages={{ REQUIRED: '…' }}
    />
    <form.Fields.Preparer1.ConfirmSignature
      label="Confirm signature"
      validationMessages={{ REQUIRED: '…' }}
    />
    <form.Fields.Preparer1.FirstName
      label="First name"
      validationMessages={{ REQUIRED: '…' }}
    />
    <form.Fields.Preparer1.LastName
      label="Last name"
      validationMessages={{ REQUIRED: '…' }}
    />
    <form.Fields.Preparer1.Signature
      label="Signature"
      validationMessages={{ REQUIRED: '…' }}
    />
    <form.Fields.Preparer1.State
      label="State"
      validationMessages={{ REQUIRED: '…' }}
    />
    <form.Fields.Preparer1.Street1
      label="Street1"
      validationMessages={{ REQUIRED: '…' }}
    />
    <form.Fields.Preparer1.Street2
      label="Street2"
      validationMessages={{ REQUIRED: '…' }}
    />
    <form.Fields.Preparer1.Zip
      label="Zip"
      validationMessages={{ REQUIRED: '…' }}
    />
  </>
)}

See PreparerFieldGroup for all sub-fields.

---

Preparer2

Second preparer field group; defined only for I-9 forms when preparers.count >= 2.

{form.Fields.Preparer2 && (
  <>
    {/* same sub-fields as Preparer1 */}
  </>
)}

See PreparerFieldGroup for all sub-fields.

---

Preparer3

Third preparer field group; defined only for I-9 forms when preparers.count >= 3.

{form.Fields.Preparer3 && (
  <>
    {/* same sub-fields as Preparer1 */}
  </>
)}

See PreparerFieldGroup for all sub-fields.

---

Preparer4

Fourth preparer field group; defined only for I-9 forms when preparers.count >= 4.

{form.Fields.Preparer4 && (
  <>
    {/* same sub-fields as Preparer1 */}
  </>
)}

See PreparerFieldGroup for all sub-fields.

---

Signature

Bound to signature. Text input for the employee's typed signature; always present.

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

SignEmployeeFormSignatureFieldProps

HookFieldProps<TextInputHookFieldProps<SignEmployeeFormRequiredValidation>>

Props accepted by useSignEmployeeForm's Fields.Signature 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<SignEmployeeFormRequiredValidation>	Custom error text keyed by validation error code.

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

---

UsedPreparer

Bound to usedPreparer. Radio group asking whether a preparer/translator assisted; defined only for I-9 forms.

{form.Fields.UsedPreparer && (
  <form.Fields.UsedPreparer
    label="Used preparer"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

UsedPreparerFieldProps

HookFieldProps<RadioGroupHookFieldProps<SignEmployeeFormRequiredValidation>>

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

Also accepts description, formHookResult from RadioGroupHookFieldProps.

---

PreparerFieldGroup

Field group exposed for each I-9 preparer/translator on useSignEmployeeForm.

Remarks

Each preparer (1–4) exposes the same nine sub-fields covering name, address, signature, and consent. Render the sub-fields directly on the group, e.g. <Fields.Preparer1.FirstName />.

Field	Component
City	ComponentType<PreparerTextFieldProps>
ConfirmSignature	ComponentType<PreparerCheckboxFieldProps>
FirstName	ComponentType<PreparerTextFieldProps>
LastName	ComponentType<PreparerTextFieldProps>
Signature	ComponentType<PreparerTextFieldProps>
State	ComponentType<PreparerSelectFieldProps>
Street1	ComponentType<PreparerTextFieldProps>
Street2	ComponentType<PreparerTextFieldProps>
Zip	ComponentType<PreparerTextFieldProps>

PreparerTextFieldProps

HookFieldProps<TextInputHookFieldProps<SignEmployeeFormRequiredValidation>>

Props accepted by the text-input preparer fields of useSignEmployeeForm (name, address, signature).

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<SignEmployeeFormRequiredValidation>	Custom error text keyed by validation error code.

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

PreparerCheckboxFieldProps

HookFieldProps<CheckboxHookFieldProps<SignEmployeeFormRequiredValidation>>

Props accepted by the confirmation checkbox preparer field of useSignEmployeeForm.

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.
validationMessages?	ValidationMessages<SignEmployeeFormRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult from CheckboxHookFieldProps.

PreparerSelectFieldProps

HookFieldProps<SelectHookFieldProps<SignEmployeeFormRequiredValidation, string>>

Props accepted by the state-select preparer field of useSignEmployeeForm.

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

Also accepts description, formHookResult, portalContainer from SelectHookFieldProps.

Validations

SignEmployeeFormRequiredValidation

SignEmployeeFormRequiredValidation = "REQUIRED"

The required-field error code emitted by every field of useSignEmployeeForm.

Remarks

Use this as the validationMessages key for any sign-employee-form field. See SignEmployeeFormErrorCodes.

Utility types

MAX_PREPARERS

const MAX_PREPARERS: 4

Maximum number of I-9 preparers and translators the form supports.

---

PREPARER_FIELDS_BY_INDEX

const PREPARER_FIELDS_BY_INDEX: SignEmployeeFormField[][]

Flat list of preparer field names per preparer slot (0-based), useful for iterating every field that belongs to a single preparer.

---

PreparerFieldSuffix

PreparerFieldSuffix = "FirstName" | "LastName" | "Street1" | "Street2" | "City" | "State" | "Zip" | "Signature" | "Agree"

Suffix segment of a preparer field name — the part that follows preparer (or preparerN) in the field key.

---

PreparerIndex

PreparerIndex = 1 | 2 | 3 | 4

One-based preparer index used to reference preparer field groups (1–4).

---

SignEmployeeBaseFieldsMetadata

Field metadata for a standard (non-I-9) employee form — only the signature and its confirmation are collected.

Remarks

This is the SignEmployeeFormFieldsMetadata variant returned when the form being signed is not an I-9. Every entry is a plain FieldMetadata.

Properties

Property	Type	Description
confirmSignature	FieldMetadata	The signature-confirmation field.
signature	FieldMetadata	The typed-signature field.

---

SignEmployeeFormData

Shape of the values managed by the I-9 sign-employee form.

Properties

Property	Type	Default value
confirmSignature	boolean	agreeValidator
preparer2Agree	boolean	agreeValidator
preparer2City	string
preparer2FirstName	string
preparer2LastName	string
preparer2Signature	string
preparer2State	string
preparer2Street1	string
preparer2Street2	string
preparer2Zip	string
preparer3Agree	boolean	agreeValidator
preparer3City	string
preparer3FirstName	string
preparer3LastName	string
preparer3Signature	string
preparer3State	string
preparer3Street1	string
preparer3Street2	string
preparer3Zip	string
preparer4Agree	boolean	agreeValidator
preparer4City	string
preparer4FirstName	string
preparer4LastName	string
preparer4Signature	string
preparer4State	string
preparer4Street1	string
preparer4Street2	string
preparer4Zip	string
preparerAgree	boolean	agreeValidator
preparerCity	string
preparerFirstName	string
preparerLastName	string
preparerSignature	string
preparerState	string
preparerStreet1	string
preparerStreet2	string
preparerZip	string
signature	string
usedPreparer	"yes" | "no"	undefined

---

SignEmployeeFormErrorCode

SignEmployeeFormErrorCode = "REQUIRED"

Union of validation error code strings emitted by the I-9 sign-employee form schema.

---

SignEmployeeFormErrorCodes

const SignEmployeeFormErrorCodes: object

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

Type Declaration

Name	Type
REQUIRED	"REQUIRED"

---

SignEmployeeFormField

SignEmployeeFormField = "preparerCity" | "preparerZip" | "preparer2City" | "preparer2Zip" | "preparer3City" | "preparer3Zip" | "preparer4City" | "preparer4Zip" | "signature" | "preparerFirstName" | "preparerLastName" | "preparerStreet1" | "preparerStreet2" | "preparerState" | "preparerSignature" | "preparerAgree" | "preparer2FirstName" | "preparer2LastName" | "preparer2Street1" | "preparer2Street2" | "preparer2State" | "preparer2Signature" | "preparer2Agree" | "preparer3FirstName" | "preparer3LastName" | "preparer3Street1" | "preparer3Street2" | "preparer3State" | "preparer3Signature" | "preparer3Agree" | "preparer4FirstName" | "preparer4LastName" | "preparer4Street1" | "preparer4Street2" | "preparer4State" | "preparer4Signature" | "preparer4Agree" | "confirmSignature" | "usedPreparer"

Field names accepted by the I-9 sign-employee form.

---

SignEmployeeFormFieldsMetadata

SignEmployeeFormFieldsMetadata = SignEmployeeBaseFieldsMetadata | SignEmployeeI9FieldsMetadata

Shape of the form.fieldsMetadata object returned by useSignEmployeeForm.

Remarks

A discriminated union keyed on whether the form is an I-9. Narrow with an in check on a preparer field before reading the I-9 entries:

const { fieldsMetadata } = form
if ('usedPreparer' in fieldsMetadata) {
  // fieldsMetadata is SignEmployeeI9FieldsMetadata
  fieldsMetadata.preparerState.options
}

---

SignEmployeeI9FieldsMetadata

Field metadata for an I-9 employee form, which additionally collects preparer/translator certification for up to four preparers.

Remarks

A superset of SignEmployeeBaseFieldsMetadata. usedPreparer is a yes/no radio and each preparer{N}State is a US-state select (StateAbbreviation); every other preparer field is a plain text FieldMetadata. Preparer entries beyond the active preparer count are still typed here but only populated once that preparer section is added.

Properties

Property	Type	Description
confirmSignature	FieldMetadata	-
preparer2Agree	FieldMetadata	-
preparer2City	FieldMetadata	-
preparer2FirstName	FieldMetadata	-
preparer2LastName	FieldMetadata	-
preparer2Signature	FieldMetadata	-
preparer2State	FieldMetadataWithOptions<"AL" | "AK" | "AZ" | "AR" | "CA" | "CO" | "CT" | "DE" | "DC" | "FL" | "GA" | "HI" | "ID" | "IL" | "IN" | "IA" | "KS" | "KY" | "LA" | "ME" | "MD" | "MA" | "MI" | "MN" | "MS" | "MO" | "MT" | "NE" | "NV" | "NH" | "NJ" | "NM" | "NY" | "NC" | "ND" | "OH" | "OK" | "OR" | "PA" | "RI" | "SC" | "SD" | "TN" | "TX" | "UT" | "VT" | "VA" | "WA" | "WV" | "WI" | "WY">	US-state select for the second preparer's address.
preparer2Street1	FieldMetadata	-
preparer2Street2	FieldMetadata	-
preparer2Zip	FieldMetadata	-
preparer3Agree	FieldMetadata	-
preparer3City	FieldMetadata	-
preparer3FirstName	FieldMetadata	-
preparer3LastName	FieldMetadata	-
preparer3Signature	FieldMetadata	-
preparer3State	FieldMetadataWithOptions<"AL" | "AK" | "AZ" | "AR" | "CA" | "CO" | "CT" | "DE" | "DC" | "FL" | "GA" | "HI" | "ID" | "IL" | "IN" | "IA" | "KS" | "KY" | "LA" | "ME" | "MD" | "MA" | "MI" | "MN" | "MS" | "MO" | "MT" | "NE" | "NV" | "NH" | "NJ" | "NM" | "NY" | "NC" | "ND" | "OH" | "OK" | "OR" | "PA" | "RI" | "SC" | "SD" | "TN" | "TX" | "UT" | "VT" | "VA" | "WA" | "WV" | "WI" | "WY">	US-state select for the third preparer's address.
preparer3Street1	FieldMetadata	-
preparer3Street2	FieldMetadata	-
preparer3Zip	FieldMetadata	-
preparer4Agree	FieldMetadata	-
preparer4City	FieldMetadata	-
preparer4FirstName	FieldMetadata	-
preparer4LastName	FieldMetadata	-
preparer4Signature	FieldMetadata	-
preparer4State	FieldMetadataWithOptions<"AL" | "AK" | "AZ" | "AR" | "CA" | "CO" | "CT" | "DE" | "DC" | "FL" | "GA" | "HI" | "ID" | "IL" | "IN" | "IA" | "KS" | "KY" | "LA" | "ME" | "MD" | "MA" | "MI" | "MN" | "MS" | "MO" | "MT" | "NE" | "NV" | "NH" | "NJ" | "NM" | "NY" | "NC" | "ND" | "OH" | "OK" | "OR" | "PA" | "RI" | "SC" | "SD" | "TN" | "TX" | "UT" | "VT" | "VA" | "WA" | "WV" | "WI" | "WY">	US-state select for the fourth preparer's address.
preparer4Street1	FieldMetadata	-
preparer4Street2	FieldMetadata	-
preparer4Zip	FieldMetadata	-
preparerAgree	FieldMetadata	-
preparerCity	FieldMetadata	-
preparerFirstName	FieldMetadata	-
preparerLastName	FieldMetadata	-
preparerSignature	FieldMetadata	-
preparerState	FieldMetadataWithOptions<"AL" | "AK" | "AZ" | "AR" | "CA" | "CO" | "CT" | "DE" | "DC" | "FL" | "GA" | "HI" | "ID" | "IL" | "IN" | "IA" | "KS" | "KY" | "LA" | "ME" | "MD" | "MA" | "MI" | "MN" | "MS" | "MO" | "MT" | "NE" | "NV" | "NH" | "NJ" | "NM" | "NY" | "NC" | "ND" | "OH" | "OK" | "OR" | "PA" | "RI" | "SC" | "SD" | "TN" | "TX" | "UT" | "VT" | "VA" | "WA" | "WV" | "WI" | "WY">	US-state select for the first preparer's address.
preparerStreet1	FieldMetadata	-
preparerStreet2	FieldMetadata	-
preparerZip	FieldMetadata	-
signature	FieldMetadata	-
usedPreparer	FieldMetadataWithOptions<boolean>	Yes/no radio: whether a preparer or translator assisted with the form.

---

Endpoints

Method	Path
GET	/v1/employees/:employeeId/forms/:formId
GET	/v1/employees/:employeeId/forms/:formId/pdf
PUT	/v1/employees/:employeeId/forms/:formId/sign