React Stripe.js reference
Learn about React components for Stripe.js and Stripe Elements.
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.
Note
This reference covers the full React Stripe.js API. If you prefer to learn by doing, check out our documentation on accepting a payment or take a look at a sample integration.
Before you begin
This doc assumes that you already have a basic working knowledge of React and that you’ve 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
Install React Stripe.js and the Stripe.js loader from the npm public registry.
Command Line
npm install --save @stripe/react-stripe-js @stripe/stripe-js
CheckoutElementsProvider
The CheckoutElementsProvider allows you to use Element components and access the Stripe object in any nested component. Render a CheckoutElementsProvider at the root of your React app so that it’s available everywhere you need it.
To use the CheckoutElementsProvider, 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 CheckoutElementsProvider.
See Create a Checkout Session for an example of what your endpoint might look like.
index.jsx
| prop | description |
|---|---|
stripe | required Stripe | null | Promise<Stripe | null> A Stripe object or a Promise resolving to a Stripe object. We recommend using the Stripe.js wrapper module to initialize a Stripe object. After you set this prop, you can’t change it. You can also pass in null or a Promise resolving to null if you’re performing an initial server-side render or when generating a static site. |
options | required Object CheckoutElementsProvider configuration options. See available options. You must provide the clientSecret of the created Checkout Session. See Create a Checkout Session for an example. |
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 CheckoutElementsProvider tree. You can only mount one of each type of Element in a single <CheckoutElementsProvider>.
CheckoutForm.jsx
| prop | description |
|---|---|
options | optional Object An object containing Element configuration options. See available options for the Payment Element. |
onBlur | optional () => void Triggered when the Element loses focus. |
onChange | optional (event: Object) => void Triggered when data exposed by this Element changes. For more information, refer to the Stripe.js reference. |
onEscape | optional (event: Object) => void Triggered when the escape key is pressed within an Element. For more information, refer to the Stripe.js reference. |
onFocus | optional () => void Triggered when the Element receives focus. |
onLoaderror | optional (event: Object) => void Triggered when the Element fails to load. For more information, refer to the Stripe.js reference. |
onLoaderStart | optional (event: Object) => void Triggered when the loader UI is mounted to the DOM and ready to be displayed. You only receive these events from the payment, paymentForm, and address Elements. For more information, refer to the Stripe.js reference. |
onReady | optional (element: Element) => void Triggered when the Element is fully rendered and can accept imperative element.focus() calls. Called with a reference to the underlying Element instance. |
Calling imperative Element methods
Props such as onFocus and onBlur are event handlers that respond to user interaction. To programmatically call methods such as focus() on the underlying Element instance, use the onReady prop to capture a reference to the Element when it mounts.
CheckoutForm.jsx
Available Element components
You can use several different kinds of Elements for collecting information on your checkout page. These are the available Elements:
| Component | Usage |
|---|---|
BillingAddressElement | Collects billing address details for more than 236 regional formats. To learn more, see the Address Element documentation. |
CurrencySelectorElement | Allows customers to select the currency for their payment with Adaptive Pricing. To learn more, see the Currency Selector Element documentation. |
ExpressCheckoutElement | Allows you to accept card or wallet payments through one or more payment buttons, including Apple Pay, Google Pay, Link, or PayPal. To learn more, see the Express Checkout Element documentation. |
PaymentElement | Collects payment details for more than 25 payment methods from around the globe. To learn more, see the Payment Element documentation. |
PaymentMethodMessagingElement | Show your customers available buy now, pay later plans. To learn more, see the Payment Method Messaging Element documentation. |
ShippingAddressElement | Collects shipping address details for more than 236 regional formats. To learn more, see the Address Element documentation. |
TaxIdElement | Collects tax ID information from your customers, including business name and tax identification number. To learn more, see the Tax ID Element documentation. |
useCheckoutElements hook
useCheckoutElements(): CheckoutValue
Use the useCheckoutElements hook in your components to get the Checkout object, which contains data from the Checkout Session, and methods to update and confirm the Session. Use useCheckoutElements inside a CheckoutElementsProvider. If you use a CheckoutFormProvider instead, use useCheckoutForm inside it.
Note
In @stripe/react-stripe-js versions before v6, use useCheckout instead.
CheckoutForm.jsx
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. To customize Elements, you respond to events and configure Elements with the appearance option. The layout of each Element stays consistent, but you can modify colors, fonts, borders, padding, and so on.
Customer location
Size
Theme
Layout
This demo only displays Google Pay or Apple Pay if you have an active card with either wallet.
Next steps
Build an integration with React Stripe.js and Elements with the Checkout Sessions API.