What to check when you move @taxbit/react-sdk to a newer version. Each section lists only the changes that may need action. The full release notes are in CHANGELOG.md in the package.

Upgrading	Effort
6.1 → 6.2	Small: check proxy allowlists and decide on usage telemetry
6.0 → 6.1	None
5.x → 6.0	Medium: check custom CSS, automated tests, and how you serve the package
4.x → 5.0	Medium: treaty-claim configuration and `useTaxbitStatus`

6.2

Action items

Usage telemetry is on by default. TaxbitQuestionnaire now sends usage events: steps shown, button presses, validation errors shown, TIN and GIIN check outcomes, and submission. They never include what the user typed. To opt out, pass telemetry={false}. See Usage telemetry.
Proxy allowlists. If you route through proxyDomain and your proxy forwards only listed paths, add telemetry/events. Without it, events fail quietly and the questionnaire still works.
CSP. No change if it already allows the SDK's API host.

Behavior changes

An invalid VAT number no longer blocks submission. If a VAT number fails the VIES check, an "Invalid" badge appears beside the VAT label on the tax information step and the summary, and the user can submit without changing it. If you relied on the form to stop users, follow up from vatStatus === 'INVALID' or the status webhook instead.
Brazil entity TINs accept the alphanumeric CNPJ: 12 letters or digits followed by 2 check digits, entered as 14 characters or as XX.XXX.XXX/XXXX-NN. Before 6.2, only the formatted, all-digit CNPJ was accepted.

6.1

No action needed. The country and phone-country pickers include 22 more jurisdictions, such as XK (Kosovo), with localized names.

6.0

6.0 brings the questionnaire to WCAG 2.1 AA. Props and useTaxbit's return shape are unchanged. The HTML structure and bundled stylesheets changed, which can affect custom CSS and automated tests.

If you have your own CSS

Change	What to do
`basic.css` and `inline.css` declare colors as `--taxbit-color-*` tokens, and several values changed for contrast	Nothing, if your overrides are class rules; they still win. Or switch to overriding the tokens. Re-check contrast if you change muted text or placeholder colors.
Next and Submit come before Back in the HTML	If you lay out `.taxbit-step-actions` as a row yourself, add `flex-direction: row-reverse` to keep Back on the left.
While busy, Next and Submit use `aria-disabled="true"` and `.taxbit-button-disabled` instead of the `disabled` attribute	If you mute buttons with `:disabled`, add `[aria-disabled='true']` to the selector.
The required asterisk is a separate `<span class="taxbit-required-marker">`	Style the span to change it. Remove any rule that adds an asterisk to the label.
Group labels are `<div class="taxbit-label">`, not `<label>`; section titles are `<h4>`	Target `.taxbit-label` without the element name.
New hooks: `.taxbit-primary-actions`, `.taxbit-secondary-actions`	Optional: use them to style the two sides of the step actions separately.

See Customizing look and feel.

If you have automated tests

Old selector	New selector
Control labelled by its field key	`getByLabelText('<visible label>')` or the control's `id`
Label text with an asterisk (`'Name*'`)	Label text without it (`'Name'`); required state is `aria-required`
Step buttons by position	`getByRole('button', { name: 'Next' })`
`toBeDisabled()` on Next or Submit	`toHaveAttribute('aria-disabled', 'true')`
A select's first option	Account for the disabled placeholder option on date and phone-country selects
Groups by structure	`getByRole('group' \| 'radiogroup', { name })`

See Test your integration.

If you serve the package yourself

The ES build now keeps each language in its own file, loaded when that language is first shown. Bundlers handle this automatically. If you copy dist/taxbit-react-sdk.js to a CDN or static folder by hand, copy every .js file in dist/ with it. The UMD build is unchanged. See Install the SDK.

Your page

A few accessibility criteria depend on the page around the SDK: a <title> for each step (use onProgress's stepTitle), <html lang>, and a place in your heading outline where h4 section titles fit. See Meet accessibility requirements.

If you validate submissions

Submitted documents can now include the certification statements and the no-other-tax-residencies confirmations as optional booleans. If you validate the submission shape strictly, allow them.

Also new

When the step changes, focus moves to the new step's title, so the page scrolls up to it after Next.
Server rendering is supported. The questionnaire renders loadingComponent on the server and hydrates cleanly.
Only the displayed language is downloaded, and every locale is fully translated.
onProgress and onError can be inline functions without causing render loops.
Self-certification and digital platform seller submissions reload correctly for returning users.
The type declarations resolve under every moduleResolution setting and type-check with skipLibCheck: false.

5.0

Action items

typesOfIncome is required with treatyClaims. Without it, or with an unrecognized value, the component throws when it starts. See W-8 expansion: FATCA and income types.
fatca={false} throws when typesOfIncome includes interest or dividends. Leave fatca unset or remove those income types.
useTaxbitStatus has a narrower shape. Its props drop questionnaire and prepopulateWithSavedData. Its return keeps statusData, isLoading, error and refreshStatus, drops serverData, refresh and refreshSubmission, and adds needsCuringDocumentation.
Submissions are stamped schema_version: "5" and carry a config object recording the SDK settings used.

New: FATCA collection, GIIN checks, and treaty claims split into general and special rates. Stylesheets and class names are unchanged from 4.x. See W-8 expansion: FATCA and income types.

5.0.1

No action needed. Returning W-9, W-8BEN, W-8BEN-E and W-8IMY filers see their full prior submission, and a saved TIN match result shows on the summary.

Next steps

Questionnaire integration guide — the full setup, auth, and submission flow
Component and hook reference — every prop, hook return value, and type
Customizing look and feel — the class reference and color tokens