react-stripe-js

@stripe/react-stripe-js is Stripe’s official React binding for Stripe.js and Stripe Elements. It provides an <Elements> context provider plus a set of prebuilt, pre-styled Element components (PaymentElement, CardElement, AddressElement, ExpressCheckoutElement, and more) that mount Stripe-hosted iframes for collecting and tokenizing payment details without the app ever touching raw card data.

Beyond individual Elements, the package also ships EmbeddedCheckoutProvider/EmbeddedCheckout for embedding Stripe’s hosted Checkout flow directly inside a page, and a separate /checkout subpath exporting a Checkout Sessions-based Elements API (CheckoutElementsProvider, useCheckoutElements) for building fully custom checkout UIs. It is maintained directly by Stripe, ships first-class TypeScript types, and is the recommended way to integrate Stripe payments into any React application.

What You Get

• An <Elements> provider that instantiates Stripe.js/Elements once and exposes it via useStripe()/useElements() to any nested component
• Prebuilt Element components for every Stripe Elements type: PaymentElement, CardElement, CardNumberElement, AddressElement, IbanElement, ExpressCheckoutElement, and more
• EmbeddedCheckoutProvider/EmbeddedCheckout components for embedding Stripe’s hosted Checkout flow inline instead of redirecting off-site
• A /checkout subpath exposing a Checkout Sessions Elements API (CheckoutElementsProvider, useCheckoutElements) for fully custom checkout UIs
• Automatic diffing of Element options between renders so only Stripe-supported updates are pushed to the live element, avoiding unnecessary remounts
• SSR-safe rendering via server/client element variants so the library doesn’t crash when rendered during Next.js or static-site server rendering

Common Use Cases

• Custom checkout pages that mount PaymentElement inside the app’s own layout and styling instead of redirecting to a hosted page
• SaaS billing/account settings pages that collect card, IBAN, or bank-account details via CardElement/IbanElement/AuBankAccountElement
• Embedded, no-redirect checkout flows built with EmbeddedCheckoutProvider/EmbeddedCheckout
• One-tap wallet checkout buttons (Apple Pay, Google Pay, Link) added via ExpressCheckoutElement to reduce checkout friction

Under The Hood

Architecture

The library is organized around React Context: Elements.tsx creates an ElementsContext that lazily resolves the stripe prop (which may be a Promise) via parseStripeProp/registerWithStripeJs, storing the resolved Stripe/StripeElements pair for consumers. Individual Element components are all generated by a single factory, createElementComponent (src/components/createElementComponent.tsx), which reads either the classic Elements context or, when running under the newer Checkout Sessions surface, the parallel CheckoutContext (src/checkout/components/CheckoutContext.tsx) via useElementsOrCheckoutContextWithUseCase. This dual-context design lets one component factory serve both the legacy Elements API and the newer Checkout Elements API without duplicating the create/mount/update/destroy lifecycle. EmbeddedCheckoutProvider/EmbeddedCheckout are a separate, parallel context+component pair for the fully hosted embedded-checkout iframe. If the context-resolution or lifecycle logic in createElementComponent changes, every exported Element component breaks at once, since none of them contain independent mounting logic.

Tech Stack

Written in TypeScript targeting esnext/strict mode, transpiled with Babel and bundled with Rollup into CJS, ESM, and UMD outputs (rollup.config.js) plus a minified UMD build for <script> tag consumption. The only runtime dependency is prop-types; @stripe/stripe-js, react, and react-dom are peer dependencies (React 16.8+ through 19, @stripe/stripe-js 9.x). Storybook is used for interactive component development, and the build pipeline includes an @arethetypeswrong/cli check (test:package-types) to catch broken package.json exports/types configuration before publish.

Code Quality

Tests live alongside source files as *.test.tsx/*.test.ts and run under Jest with ts-jest and React Testing Library (@testing-library/react, @testing-library/react-hooks), covering the Elements provider, individual Element wrapper behavior, the Checkout providers, and pure utility functions like extractAllowedOptionsUpdates and isEqual. Linting is enforced via ESLint (Airbnb config + eslint-plugin-react/react-hooks/jsx-a11y) with --max-warnings=0, Prettier formatting is checked in CI, and a GitHub Actions workflow (.github/workflows/build.yml) runs lint, unit tests, package-type checks, and tsc typechecking on every change. Error handling around element teardown is deliberately defensive — element.destroy() calls are wrapped in try/catch since Stripe.js can throw if an element was already destroyed.

What Makes It Unique

Rather than exposing a single generic “Element” component, the library generates a distinct, strongly-typed component per Stripe Elements type from one internal factory, giving consumers IDE autocomplete and type-checked props per element while keeping the create/update/destroy lifecycle implementation in exactly one place. Its dual support for both the original Elements API and the newer Checkout Sessions Elements API (via a shared context resolution layer) lets the same component set serve two different Stripe integration models without a breaking rewrite, and the built-in options-diffing (extractAllowedOptionsUpdates) avoids the common integration bug of accidentally remounting a payment iframe on every parent re-render.