useSignCompanyForm

useSignCompanyForm(props: UseSignCompanyFormProps): HookLoadingResult | UseSignCompanyFormReady

Headless hook for signing a company form — displays the form PDF and collects a typed signature with confirmation checkbox.

Remarks

The hook fetches the company form metadata and PDF, then exposes the BaseFormHookReady contract with Fields, fieldsMetadata, onSubmit, and error handling. Use data.companyForm to display the form's title and description, and data.pdfUrl to render the document for review before signing. Both signature and confirmSignature are always required.

Example

Example

import {
  useSignCompanyForm,
  SDKFormProvider,
  type UseSignCompanyFormReady,
} from '@gusto/embedded-react-sdk'

function SignFormPage({ formId }: { formId: string }) {
  const signForm = useSignCompanyForm({ formId })

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

  return <SignFormReady signForm={signForm} />
}

function SignFormReady({ signForm }: { signForm: UseSignCompanyFormReady }) {
  const { Fields } = signForm.form

  const handleSubmit = async () => {
    const result = await signForm.actions.onSubmit()
    if (result) {
      console.log('Signed form:', result.data.uuid)
    }
  }

  return (
    <SDKFormProvider formHookResult={signForm}>
      <form
        onSubmit={e => {
          e.preventDefault()
          void handleSubmit()
        }}
      >
        <h2>{signForm.data.companyForm.title}</h2>
        {signForm.data.pdfUrl && (
          <iframe src={signForm.data.pdfUrl} title="Form document" width="100%" height="600" />
        )}
        <Fields.Signature
          label="Signature"
          description="Type your full legal name"
          validationMessages={{ REQUIRED: 'Signature is required' }}
        />
        <Fields.ConfirmSignature
          label="I agree to the terms above"
          validationMessages={{ REQUIRED: 'You must confirm to sign this form' }}
        />
        <button type="submit" disabled={signForm.status.isPending}>
          {signForm.status.isPending ? 'Signing...' : 'Sign form'}
        </button>
      </form>
    </SDKFormProvider>
  )
}

Props

UseSignCompanyFormProps

Props for useSignCompanyForm.

Property	Type	Description
formId	string	UUID of the company form to sign.
defaultValues?	Partial<SignCompanyFormData>	Pre-fill form values (for example, pre-populate the signature field).
optionalFieldsToRequire?	SignCompanyFormOptionalFieldsToRequire	Promote optional fields to required. Both fields are already required by default, so this is typically unnecessary.
shouldFocusError?	boolean	Auto-focus the first invalid field on submit. Defaults to true; set to false when using composeSubmitHandler.
validationMode?	"onChange" | "onBlur" | "onSubmit" | "onTouched" | "all"	When validation runs. Passed through to react-hook-form; defaults to 'onSubmit'.

Returns

HookLoadingResult | UseSignCompanyFormReady

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

UseSignCompanyFormResult

UseSignCompanyFormResult = HookLoadingResult | UseSignCompanyFormReady

Result of useSignCompanyForm — a discriminated union on isLoading.

---

UseSignCompanyFormReady

Ready-state shape returned by useSignCompanyForm 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, or undefined on validation or API failure.
data	object	Loaded data — the company form entity and a preview PDF URL.
data.companyForm	Form	The company form entity fetched from the API (includes uuid, title, description).
data.pdfUrl	string | null	URL to the form's PDF document, or null when the document URL is not available.
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	SignCompanyFormFields	-
form.fieldsMetadata	SignCompanyFormFieldsMetadata	-
form.getFormSubmissionValues	() => SignCompanyFormData | undefined	-
form.hookFormInternals	HookFormInternals<SignCompanyFormData>	-
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

SignCompanyFormFields

Field components exposed by useSignCompanyForm on form.Fields.

Property	Type	Description
ConfirmSignature	ComponentType<ConfirmSignatureFieldProps>	Bound to confirmSignature. Checkbox confirming the signature and agreeing to the form's terms; always required.
Signature	ComponentType<SignatureFieldProps>	Bound to signature. Text input for the signer's typed name; always required.

---

ConfirmSignature

Bound to confirmSignature. Checkbox confirming the signature and agreeing to the form's terms; always required.

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

ConfirmSignatureFieldProps

HookFieldProps<CheckboxHookFieldProps<SignCompanyFormRequiredValidation>>

Props accepted by useSignCompanyForm'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<SignCompanyFormRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult from CheckboxHookFieldProps.

---

Signature

Bound to signature. Text input for the signer's typed name; always required.

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

SignatureFieldProps

HookFieldProps<TextInputHookFieldProps<SignCompanyFormRequiredValidation>>

Props accepted by useSignCompanyForm'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<SignCompanyFormRequiredValidation>	Custom error text keyed by validation error code.

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

Validations

SignCompanyFormRequiredValidation

SignCompanyFormRequiredValidation = "REQUIRED"

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

Remarks

Use this as the validationMessages key for any sign-company-form field. See SignCompanyFormErrorCodes.

Utility types

SignCompanyFormData

Shape of the values managed by the sign-company form.

Properties

Property	Type
confirmSignature	boolean
signature	string

---

SignCompanyFormErrorCode

SignCompanyFormErrorCode = "REQUIRED"

Union of validation error code strings emitted by the sign-company-form schema.

---

SignCompanyFormErrorCodes

const SignCompanyFormErrorCodes: object

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

Type Declaration

Name	Type
REQUIRED	"REQUIRED"

---

SignCompanyFormField

SignCompanyFormField = "signature" | "confirmSignature"

Field names accepted by the sign-company form.

---

SignCompanyFormFieldsMetadata

Field	Type
confirmSignature	FieldMetadata
signature	FieldMetadata

Shape of the form.fieldsMetadata object returned by useSignCompanyForm.

---

SignCompanyFormOptionalFieldsToRequire

SignCompanyFormOptionalFieldsToRequire = OptionalFieldsToRequire<typeof requiredFieldsConfig>

Optional fields that may be promoted to required for the sign-company form.

Remarks

Both fields of this form are already required by default, so passing this is typically unnecessary.

Endpoints

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