React Stripe.js

React components for
Stripe.js and Elements.

Requirements

The minimum supported version of React is v16.8. If you use an older version,
upgrade React to use this library. If you prefer not to upgrade your React
version, we recommend using legacy
react-stripe-elements.

Getting started

• Build a custom checkout page using the Checkout Sessions API
• Add React Stripe.js to your React app
• Try it out using CodeSandbox

Documentation

• React Stripe.js reference
• Migrate from react-stripe-elements
• Legacy react-stripe-elements docs
• Examples

Build a custom checkout page

For a new custom checkout page, we recommend the
Checkout Sessions API
with ui_mode: 'elements'. This lets you combine Stripe Elements with your own
React layout while Checkout Sessions manages the checkout state. If you want to
own every part of your checkout, the lower-level
Payment Intents API
provides more fine-grained control, but requires significantly more code and
ongoing maintenance.

First, install React Stripe.js and
Stripe.js.

npm install @stripe/react-stripe-js @stripe/stripe-js

Create a Checkout Session on your server using trusted product and pricing data,
then return its client secret:

// POST /create-checkout-session
const session = await stripe.checkout.sessions.create({
  ui_mode: 'elements',
  mode: 'payment',
  return_url: 'https://example.com/order/123/complete',
  line_items: [
    {
      price_data: {
        currency: 'usd',
        product_data: {name: 'T-shirt'},
        unit_amount: 1099,
      },
      quantity: 1,
    },
  ],
});

if (!session.client_secret) {
  throw new Error('Checkout Session is missing a client secret.');
}

res.json({clientSecret: session.client_secret});

Client:

import React, {useState} from 'react';
import {createRoot} from 'react-dom/client';
import {loadStripe} from '@stripe/stripe-js';
import {
  PaymentElement,
  CheckoutElementsProvider,
  useCheckoutElements,
} from '@stripe/react-stripe-js/checkout';

const CheckoutForm = () => {
  const result = useCheckoutElements();
  const [errorMessage, setErrorMessage] = useState(null);
  const [isSubmitting, setIsSubmitting] = useState(false);

  const handleSubmit = async (event) => {
    event.preventDefault();

    if (result.type !== 'success' || !result.checkout.canConfirm) {
      return;
    }

    setIsSubmitting(true);
    setErrorMessage(null);

    try {
      const confirmResult = await result.checkout.confirm({
        returnUrl: 'https://example.com/order/123/complete',
      });

      if (confirmResult.type === 'error') {
        setErrorMessage(confirmResult.error.message);
      }
    } catch (error) {
      setErrorMessage(
        error instanceof Error ? error.message : 'An unexpected error occurred.'
      );
    } finally {
      setIsSubmitting(false);
    }
  };

  if (result.type === 'loading') {
    return <div>Loading checkout...</div>;
  }

  if (result.type === 'error') {
    return <div>{result.error.message}</div>;
  }

  const {checkout} = result;

  return (
    <>
      <ul>
        {checkout.lineItems.map((lineItem) => (
          <li key={lineItem.id}>
            {lineItem.name}: {lineItem.total.amount}
          </li>
        ))}
      </ul>
      <p>Total: {checkout.total.total.amount}</p>
      <form onSubmit={handleSubmit}>
        <PaymentElement />
        <button type="submit" disabled={!checkout.canConfirm || isSubmitting}>
          {isSubmitting ? 'Processing...' : 'Pay'}
        </button>
        {errorMessage && <div>{errorMessage}</div>}
      </form>
    </>
  );
};

// Use the publishable key for the same account that created the Checkout Session.
const stripePromise = loadStripe('pk_test_...');

const clientSecretPromise = fetch('/create-checkout-session', {
  method: 'POST',
}).then(async (response) => {
  const body = await response.json();

  if (!response.ok) {
    throw new Error(body.error ?? 'Unable to create a Checkout Session.');
  }

  return body.clientSecret;
});

const options = {
  clientSecret: clientSecretPromise,
  elementsOptions: {
    appearance: {
      theme: 'stripe',
    },
  },
};

const App = () => (
  <CheckoutElementsProvider stripe={stripePromise} options={options}>
    <CheckoutForm />
  </CheckoutElementsProvider>
);

createRoot(document.getElementById('root')).render(<App />);

TypeScript support

React Stripe.js is packaged with TypeScript declarations. Some types are pulled
from @stripe/stripe-js—be sure to add
@stripe/stripe-js as a dependency to your project for full TypeScript support.

Typings in React Stripe.js follow the same
versioning policy as
@stripe/stripe-js.

Contributing

This project is maintained by Stripe and does not accept external pull requests.
If you have feedback or ideas, please
open an issue.