Props, hooks, types, status enums, callbacks, and CSS customization for @taxbit/react-sdk. For setup, see the Integration guide.

<TaxbitQuestionnaire/> props

The primary component for collecting tax documentation. Import it from @taxbit/react-sdk and render it in your React application.

Resubmission behavior

On mount the component fetches any prior submission for the questionnaire type and adapts:

Partial progress is not saved. The SDK persists only on submit — closing or navigating away mid-flow discards entries and leaves dataCollectionStatus unchanged. The server sets INCOMPLETE when a submission fails validation or previously valid data no longer meets requirements, not on an abandoned session. Use statusData.needsResubmission as the canonical signal to route a user back through.

useTaxbit hook

Read a user's tax documentation status and data without rendering the form, and generate the completed document PDF. Use it to drive your own UI — for example, to decide whether to route someone into <TaxbitQuestionnaire/> or to show a "documentation complete" state.

Unlike the component, the hook has no demoMode: a valid bearerToken is always required.

Parameters

Returns

Types

The TypeScript shapes referenced in the props and hook tables above. The SDK exports these, so you can import them for your own typing.

Progress

The object passed to your onProgress callback on every navigation event (Next, Back, Cancel, Submit). Use it to track where the user is in the flow.

type Progress = {
  language: Locale;
  percentComplete: number;
  stepId: StepId;
  stepIndex: number;   // 0-based
  stepNumber: number;  // 1-based
  stepTitle: string;   // localized
  steps: StepId[];
  totalSteps: number;
};

Common StepId values — the active sequence depends on the questionnaire and flow (Progress.steps lists what's actually shown).

ClientTaxDocumentationStatus

Returned by useTaxbit().statusData. Each questionnaire key is undefined until data is submitted for that type.

type ClientTaxDocumentationStatus = {
  dpsQuestionnaire?: {
    dataCollectionStatus: 'COMPLETE' | 'INCOMPLETE';
    expirationDate?: string;        // 3 years after last submission
    needsResubmission?: boolean;
    vatStatus?: VatStatus;
    vatValidationDate?: string;
  };
  wFormQuestionnaire?: {
    dataCollectionStatus: 'COMPLETE' | 'INCOMPLETE';
    type: 'W-9' | 'W-8BEN' | 'W-8BEN-E' | 'W-8IMY';
    expirationDate?: string;
    issues?: QuestionnaireIssue[];
    needsResubmission?: boolean;
    tinStatus?: TinStatus;
    tinValidationDate?: string;
    treatyClaimStatus?: 'VALID' | 'INVALID';
  };
  selfCertification?: {
    dataCollectionStatus: 'COMPLETE' | 'INCOMPLETE';
    issues?: QuestionnaireIssue[];
    needsResubmission?: boolean;
  };
};

Status enums

The string values that appear on the status fields above (tinStatus, vatStatus, and questionnaire issues). Match against them to decide what to show or do next.

TinStatus

IRS TIN validation; W-9 only.

VatStatus

VIES VAT validation; DPS only.

QuestionnaireIssue

Found on wFormQuestionnaire.issues and selfCertification.issues.

type QuestionnaireIssue = {
  issueType: IssueType;
  createdAt: string;
  details: { field: string; description: string }[];
};

SDK ↔ API endpoint mapping

The SDK makes these calls for you — useful for debugging and monitoring.

The documentUrl is short-lived; the hook re-polls about every 4 minutes to refresh it before it expires.

Stylesheets

The form is semantic HTML with taxbit- namespaced classes. Import one built-in stylesheet, then override classes in your own CSS.

Supported languages

The language prop accepts any tag in the Locale type — the 53 codes below. The account owner can also switch language in-form (hide the dropdown with CSS). The in-form picker shows a subset: roughly 45 in DPS and Self-Certification flows and 19 in W-Form. Defaults are en-us (W-Form) and en-gb (DPS, Self-Certification).

Locale tags (53)

W-Form in-form options (19)

Compatibility

@taxbit/react-sdk supports React 16 through 19 (declared as a peer dependency). TypeScript type definitions are bundled with the package — no separate @types install needed.