React Stripe.js reference

React Stripe.js is a thin wrapper around Stripe Elements. It allows you to add Elements to any React app.

The Stripe.js reference covers complete Elements customization details.

You can use Elements with any Stripe product to collect online payments. To find the right integration path for your business, explore our docs.

Before you begin

This doc assumes that you already have a basic working knowledge of React and that you have already set up a React project. If you’re new to React, we recommend that you take a look at the Getting Started guide before continuing.

Setup

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

Checkout provider

The CheckoutProvider allows you to use Element components and access the Stripe object in any nested component. Render a CheckoutProvider at the root of your React app so that it’s available everywhere you need it.

To use the CheckoutProvider, call loadStripe from @stripe/stripe-js with your publishable key. The loadStripe function asynchronously loads the Stripe.js script and initializes a Stripe object. Pass the returned Promise to the CheckoutProvider.

See Create a Checkout Session for an example of what your endpoint might look like.

import {CheckoutProvider} from '@stripe/react-stripe-js';
import {loadStripe} from '@stripe/stripe-js';

// Make sure to call `loadStripe` outside of a component’s render to avoid
// recreating the `Stripe` object on every render.
const stripePromise = loadStripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

const fetchClientSecret = () => {
  return fetch('/create-checkout-session', {method: 'POST'})
    .then((response) => response.json())
    .then((json) => json.checkoutSessionClientSecret)
};

export default function App() {
  return (
    <CheckoutProvider stripe={stripePromise} options={{fetchClientSecret}}>
      <CheckoutForm />
    </CheckoutProvider>
  );
}

Element components

Element components allow you to securely collect payment information in your React app and place the Elements wherever you want on your checkout page. You can also customize the appearance.

You can mount individual Element components inside of your CheckoutProvider tree. You can only mount one of each type of Element in a single <CheckoutProvider>.

import {PaymentElement} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  return (
    <form>
      <PaymentElement />
      <button>Submit</button>
    </form>
  );
};

export default CheckoutForm;

Available Element components

You can use several different kinds of Elements for collecting information on your checkout page. These are the available Elements:

useCheckout hook

useCheckout(): CheckoutContextValue | null

Use the useCheckout hook in your components to get the Checkout object, which contains data from the Checkout Session, and methods to update and confirm the Session.

import {useCheckout, PaymentElement} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  const checkout = useCheckout();

  const handleSubmit = async (event) => {
    // We don't want to let default form submission happen here,
    // which would refresh the page.
    event.preventDefault();

    const result = await checkout.confirm();

    if (result.type === 'error') {
      // Show error to your customer (for example, payment details incomplete)
      console.log(result.error.message);
    } else {
      // Your customer will be redirected to your `return_url`. For some payment
      // methods like iDEAL, your customer will be redirected to an intermediate
      // site first to authorize the payment, then redirected to the `return_url`.
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <PaymentElement />
      <button>Submit</button>
    </form>
  )
};

export default CheckoutForm;

Customization and styling

Each element is mounted in an iframe, which means that Elements probably won’t work with any existing styling and component frameworks that you have. Despite this, you can still configure Elements to match the design of your site. Customizing Elements consists of responding to events and configuring Elements with the appearance option. The layout of each Element stays consistent, but you can modify colors, fonts, borders, padding, and so on.