Component and hook reference

Props, hooks, types, status enums, callbacks, and CSS customization for @taxbit/react-sdk.

TaxbitQuestionnaire

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

import '@taxbit/react-sdk/style/inline.css';
import { TaxbitQuestionnaire } from '@taxbit/react-sdk';

Props

Resubmission behavior

The component automatically fetches previously submitted data for the specified questionnaire type:

Use statusData.needsResubmission (from the useTaxbit hook) as the canonical signal for when to send a user back through the questionnaire. See Monitoring and remediation for how to build resubmission flows.

useTaxbit hook

Access the account owner's tax documentation status, server data, and PDF generation without rendering the questionnaire UI. Unlike the TaxbitQuestionnaire component, the hook has no demoMode — a valid bearerToken is always required.

import { useTaxbit } from '@taxbit/react-sdk';

const result = useTaxbit({ bearerToken, questionnaire, onError });

Parameters

Return values

TypeScript types

Progress

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

StepId values

ClientTaxDocumentationStatus

Returned by useTaxbit().statusData. Each questionnaire key is undefined if no data has been 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

TinStatus

US TIN validation status via IRS verification. Only applies to W-9 submissions.

VatStatus

VAT number validation via the VIES system. Only applies to DPS questionnaires.

QuestionnaireIssue

type QuestionnaireIssue = {
  issueType: IssueType;       // see table below
  createdAt: string;
  details: IssueDetail[];    // per-field validation details
};

type IssueDetail = {
  field: string;
  description: string;
};

issueType values

CSS customization

The SDK renders semantic HTML with namespaced CSS classes. You can style it to match your platform using one of three built-in stylesheets, or write your own CSS targeting the same class names.

Built-in stylesheets

Each question and screen has its own unique class name, namespaced to prevent conflicts with your app's styles. Override any class in your own CSS file to match fonts, colors, spacing, and layout to your platform.

For examples of branded integrations, see the Adaptive mode page.

Loading component

While the SDK fetches status from the server, it displays "Retrieving interview status..." by default. Customize this with the loadingComponent prop:

<TaxbitQuestionnaire
  bearerToken={token}
  questionnaire="W-FORM"
  loadingComponent={<div>Loading...</div>}
/>

Supported languages

The language prop accepts the locale codes below. End users can also switch language via a dropdown in the UI (hideable with CSS).

DPS and Self-Certification (53 languages)

W-FORM (~20 languages)

SDK ↔ API endpoint mapping

The SDK makes these API calls under the hood. You don't call these directly when using the SDK, but understanding the mapping helps with debugging and monitoring.

The documentUrl returned by the hook expires in 5 minutes. The hook auto-refreshes by re-polling when the URL nears expiration.