Props, hooks, types, status enums, callbacks, and CSS customization for @taxbit/react-sdk. For setup, see the Questionnaire 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.

<TaxbitCuringDocumentation/> props

A focused component that clears specific W-8 validation issues in place. Import it from @taxbit/react-sdk. For the full embedding walkthrough, see the Curing integration guide.

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

The component accepts one of three prop shapes. Exactly one applies per call site.

Common to all shapes

Demo mode

Renders against a synthesized issue list. No network calls, no token.

Production — region (default)

Production — through a proxy

Same as region, with region replaced by:

Mount-time behavior

On mount, the component fetches statusData for the user and derives the curable issue list. The widget renders null and emits a dev-mode warning if no OPEN curable issue exists. Gate the mount on useTaxbit().needsCuringDocumentation to avoid the round-trip.

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

useTaxbitStatus hook

A status-only version of useTaxbit. It never fetches the prior submission, so no previously submitted personal data reaches the browser. Use it when you only need to know whether the user must act, for example to decide whether to show <TaxbitCuringDocumentation />.

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

const { needsCuringDocumentation, isLoading } = useTaxbitStatus({ bearerToken });

Parameters: bearerToken, onError, and region or proxyDomain + proxyHeaders, as for useTaxbit. It takes no questionnaire; the status covers every questionnaire.

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;
  };
};

Curing types

Types used by <TaxbitCuringDocumentation/> and the curing read flow. See Reading curing statuses for how these surface in practice.

CurableIssueType

type CurableIssueType =
  | 'US_INDICIA'
  | 'TREATY_COUNTRY_MISMATCH'
  | 'CARE_OF_PERMANENT_ADDRESS'
  | 'PO_BOX_PERMANENT_ADDRESS';

Which doc types each applies to:

ReasonableExplanationType

type ReasonableExplanationType =
  | 'STUDENT'
  | 'TEACHER_OR_TRAINEE'
  | 'DIPLOMAT'
  | 'SPOUSE_OR_CHILD'
  | 'DO_NOT_MEET_SUBSTANTIAL_PRESENCE_TEST'
  | 'CLOSER_CONNECTION_EXCEPTION';

Only relevant when the user has an open US_INDICIA issue. The first four require no additional fields. DO_NOT_MEET_SUBSTANTIAL_PRESENCE_TEST adds the SPT day-count fields. CLOSER_CONNECTION_EXCEPTION adds the closer-connection fields.

ClientCuringSubmission

type ClientCuringSubmission = {
  fileName?: string;
  fileMimeType?: string;
  reasonableExplanationData?: {
    explanationType: ReasonableExplanationType;
    signatureName?: string;          // populated from the prior submission's accountHolder.name
    signatureDate?: string;          // ISO timestamp, stamped at submit
    // Present only when explanationType === 'DO_NOT_MEET_SUBSTANTIAL_PRESENCE_TEST'
    daysInCurrentYear?: number;
    daysInFirstPrecedingYear?: number;
    daysInSecondPrecedingYear?: number;
    weightedTotal?: number;
    // Present only when explanationType === 'CLOSER_CONNECTION_EXCEPTION'
    usPresentDaysCertified?: boolean;
    closerConnectionCountryCode?: string;
    closerConnectionReason?: string;
  };
};

Same shape across demo onSubmit and production onSuccess / onSettled.

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.

Issue status

The status field on a curable W-8 issue is its current remediation state ('OPEN' | 'IN_REVIEW' | 'RESOLVED'). See Reading curing statuses.

Transitions: OPEN → IN_REVIEW (filer submits), IN_REVIEW → RESOLVED (reviewer accepts), IN_REVIEW → OPEN (reviewer rejects / requests more). RESOLVED is terminal.

QuestionnaireIssue

Found on wFormQuestionnaire.issues and selfCertification.issues.

type QuestionnaireIssue = {
  issueType: IssueType;
  status: 'OPEN' | 'IN_REVIEW' | 'RESOLVED';   // present on curable W-8 issues
  createdAt: string;
  details: { field: string; description: string }[];
};

SDK ↔ API endpoint mapping

The SDK makes these calls for you — useful for debugging and monitoring. Every call goes to the region's API host, or to your proxyDomain when one is set.

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

Curing makes these calls:

Content-Type is left to fetch so the multipart boundary survives — don't override it.

Stylesheets

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

inline.css and basic.css declare their colors as --taxbit-color-* custom properties on :root; minimal.css declares only the four status colors. Override the tokens to theme the form.

For the token list, the full class reference and override patterns, see Customizing look and feel.

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).

Only the displayed language is downloaded. Switching language fetches the new one once and keeps the current one on screen until it arrives; if the fetch fails, the current language stays.

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. They resolve under every moduleResolution setting, including node16 / nodenext and CommonJS require, and type-check with skipLibCheck: false. For upgrade notes between versions, see the Upgrade guide.