react-connect-js

@stripe/react-connect-js is Stripe’s official React wrapper around Connect.js, the vanilla-JS SDK that renders Stripe’s prebuilt embedded UI components for Connect platforms. Rather than hand-building dashboards for payouts, disputes, tax settings, or account onboarding, platforms drop in typed React components like <ConnectPayments /> or <ConnectAccountOnboarding /> and get Stripe-hosted UI that stays in sync with a connected account’s state.

Every component follows the same pattern: a ConnectComponentsProvider supplies a ConnectInstance created via loadConnectAndInitialize with a fetchClientSecret callback, and each component wraps a native custom element created by Connect.js inside a plain div, wiring props through imperative setter calls and forwarding onLoaderStart/onLoadError callbacks uniformly. The repo ships parallel GA (/ga) and preview (/preview) packages so platforms can adopt still-evolving embedded components ahead of general availability.

What You Get

• Typed React components for every Connect embedded UI: payments, payouts, onboarding, account management, disputes, tax registrations/settings, financial accounts, issuing cards, and reports.
• A ConnectComponentsProvider/useConnectComponents context pair that threads a single ConnectInstance to every embedded component in the tree.
• Consistent onLoaderStart/onLoadError callback props across all components for handling load state and errors uniformly.
• Parallel GA (/ga) and preview (/preview) package builds so teams can try upcoming embedded components before they graduate to general availability.

Common Use Cases

• Marketplace or platform embeds a ConnectAccountOnboarding flow so connected sellers can complete KYC without leaving the platform’s own app.
• Platform renders ConnectPayouts and ConnectBalances so connected accounts can review payout history and available balance in-product.
• Support or ops teams use ConnectPaymentDetails and ConnectPaymentDisputes to investigate individual charges and disputes inline.
• Platform surfaces ConnectTaxRegistrations and ConnectTaxSettings so connected accounts can self-serve tax compliance setup.

Under The Hood

Architecture The repo is two near-identical packages (/ga and /preview) each built around three files: Components.tsx (the ~20 exported Connect* components), ConnectComponents.tsx (the ConnectComponentsProvider/useConnectComponents context pair), and useCreateComponent.tsx (the shared hook every component calls). useCreateComponent lazily creates the underlying Connect.js custom element via connectInstance.create(tagName) inside a useLayoutEffect, mounts it into a wrapper div ref, and returns it so callers can wire props. There is no internal state store, routing, or build system beyond this — it is a flat adapter layer, so a change to useCreateComponent or the setter-bridge hook (useUpdateWithSetter) ripples through every single component.

Tech Stack TypeScript targeting React >=16.8 as a peer dependency, with @stripe/connect-js as the actual implementation the components delegate to (also a peer dependency). Built with Rollup (rollup-plugin-typescript2, rollup-plugin-terser) into CJS, ESM, and .d.ts outputs; tested with Jest, ts-jest, and jsdom; linted with ESLint (typescript-eslint, eslint-plugin-react/react-hooks) and Prettier. GitHub Actions run a test.yml CI workflow and an npm_auto_release.yml workflow that automates npm publishes.

Code Quality Only one test file exists (Components.test.ts), and it checks a single naming-convention invariant — every exported component starts with Connect — rather than any component’s actual rendering or prop-wiring behavior; no other unit or integration tests were found. Error handling is present but narrow: useUpdateWithSetter wraps each setter call in try/catch and logs failures with console.error, and useCreateComponent does the same around a version-tagging call. TypeScript types are used consistently throughout and reuse @stripe/connect-js’s own exported types (LoadError, CollectionOptions, etc.) directly, giving strong compile-time safety despite the thin runtime test coverage. ESLint, Prettier, and tsc typecheck are enforced via the test script and CI.

API Design The library’s core ergonomic choice is making every embedded UI behave like a controlled React component: props map one-to-one onto imperative setter calls on the underlying custom element via a single shared hook, so consumers never touch the custom-element API directly. Getting started takes two steps — wrap the tree in ConnectComponentsProvider with a connectInstance from loadConnectAndInitialize, then render named components like <ConnectPayments />. Naming is highly consistent (Connect-prefixed components, verb-based onX callback props), and types are re-exported straight from @stripe/connect-js for first-class autocomplete. The tradeoff: since Connect.js does the real work, this package is a thin, well-executed adapter rather than a novel abstraction in its own right.