Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
Security
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Quickstart
Stripe Shell
Stripe CLI
Dashboard
Stripe for Visual Studio Code
Webhooks
File uploads
Error handling
API
Tour
Keys
Libraries
Upgrades
Rate limits
Card testing
Expanding responses
Domains and IP addresses
Search
Building With Stripe
React Stripe.js
Prebuilt iOS UI
Prebuilt Android UI
Extensions
Connectors
Samples
Checklist
Feedback
HomeDeveloper tools

React Stripe.js reference

React components for Stripe.js and Stripe Elements

See the code

Want to see how React Stripe.js works or help develop it? Check out the project on GitHub.

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.

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.

Prerequisites

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

Install React Stripe.js and the Stripe.js loader from the npm public registry.

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

Elements provider

The Elements provider allows you to use Element components and access the Stripe object in any nested component. Render an Elements provider at the root of your React app so that it is available everywhere you need it.

To use the Elements provider, 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 Elements.

index.js
import {Elements} 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'
); function App() { const options = { // passing the client secret obtained from the server clientSecret: '{{CLIENT_SECRET}}', }; return ( <Elements stripe={stripePromise} options={options}> <CheckoutForm /> </Elements> ); };
prop
description

stripe

required Stripe | null | Promise<Stripe | null>

A Stripe object or a Promise resolving to a Stripe object. The easiest way to initialize a Stripe object is with the Stripe.js wrapper module. After this prop has been set, it can not be changed.

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

optional Object

Optional Elements configuration options. See available options. Once the stripe prop has been set, these options can’t be changed. If you want to use Payment Element, it is required to pass in the clientSecret.

Element components

Element components provide a flexible way to securely collect payment information in your React app.

You can mount individual Element components inside of your Elements tree. Note that you can only mount one of each type of Element in a single <Elements> group.

CheckoutForm.js
import {PaymentElement} from '@stripe/react-stripe-js'; const CheckoutForm = () => { return ( <form> <PaymentElement /> <button>Submit</button> </form> ); };
prop
description

id

optional string

Passes through to the Element’s container.

className

optional string

Passes through to the Element’s container.

options

optional Object

An object containing Element configuration options. See available options for the Payment Element or available options for individual payment method Elements.

onBlur

optional () => void

Triggered when the Element loses focus.

onChange

optional (event: Object) => void

Triggered when data exposed by this Element is changed (for example, when there is an error).

For more information, refer to the Stripe.js reference.

onClick

optional (event: Object) => void

Triggered by the <PaymentRequestButtonElement> when it is clicked.

For more information, refer to the Stripe.js reference.

onFocus

optional () => void

Triggered when the Element receives focus.

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.

Available Element components

There are many different kinds of Elements, useful for collecting different kinds of payment information. These are the available Elements today.

Component
Usage
PaymentElementCollects payment details from 18+ payment methods from around the globe.
CardElementA flexible single-line input that collects all necessary card details.
CardNumberElementCollects the card number.
CardExpiryElementCollects the card‘s expiration date.
CardCvcElementCollects the card‘s CVC number.
PaymentRequestButtonElementAn all-in-one checkout button backed by either Apple Pay or the Payment Request API. Refer to the Payment Request Button docs for more information.
AuBankAccountElementCollects Australian bank account information (BSB and account number) for use with BECS Direct Debit payments.
IbanElementThe International Bank Account Number (IBAN). Available for SEPA countries.
IdealBankElementThe customer’s bank, for use with iDEAL payments.
FpxBankElementThe customer’s bank, for use with FPX payments.
AfterpayClearpayMessageElementDisplays installments messaging for Afterpay payments.

useElements hook

useElements(): Elements | null

To safely pass the payment information collected by the Payment Element to the Stripe API, access the Elements instance so that you can use it with stripe.confirmPayment. If you use the React Hooks API, then useElements is the recommended way to access a mounted Element. If you need to access an Element from a class component, use ElementsConsumer instead.

Note that if you pass a Promise to the Elements provider and the Promise has not yet resolved, then useElements will return null.

CheckoutForm.js
import {useStripe, useElements, PaymentElement} from '@stripe/react-stripe-js'; const CheckoutForm = () => { const stripe = useStripe(); const elements = useElements(); const handleSubmit = async (event) => { // We don't want to let default form submission happen here, // which would refresh the page. event.preventDefault(); if (!stripe || !elements) { // Stripe.js has not yet loaded. // Make sure to disable form submission until Stripe.js has loaded. return; } const result = await stripe.confirmPayment({ //`Elements` instance that was used to create the Payment Element elements, confirmParams: { return_url: "https://example.com/order/123/complete", }, }); if (result.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 disabled={!stripe}>Submit</button> </form> ) };

useStripe hook

useStripe(): Stripe | null

The useStripe hook returns a reference to the Stripe instance passed to the Elements provider. If you need to access the Stripe object from a class component, use ElementsConsumer instead.

Note that if you pass a Promise to the Elements provider and the Promise has not yet resolved, then useStripe will return null.

CheckoutForm.js
import {useStripe, useElements, PaymentElement} from '@stripe/react-stripe-js'; const CheckoutForm = () => { const stripe = useStripe(); const elements = useElements(); const handleSubmit = async (event) => { // We don't want to let default form submission happen here, // which would refresh the page. event.preventDefault(); if (!stripe || !elements) { // Stripe.js has not yet loaded. // Make sure to disable form submission until Stripe.js has loaded. return; } const result = await stripe.confirmPayment({ //`Elements` instance that was used to create the Payment Element elements, confirmParams: { return_url: "https://example.com/order/123/complete", }, }); if (result.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 disabled={!stripe}>Submit</button> </form> ) };

ElementsConsumer

To safely pass the payment information collected by the Payment Element to the Stripe API, access the Elements instance so that you can use it with stripe.confirmPayment. If you need to access the Stripe object or an Element from a class component, then ElementsConsumer provides an alternative to the useElements and useStripe hooks.

CheckoutForm.js
import {ElementsConsumer, PaymentElement} from '@stripe/react-stripe-js'; class CheckoutForm extends React.Component { handleSubmit = async (event) => { // We don't want to let default form submission happen here, // which would refresh the page. event.preventDefault(); const {stripe, elements} = this.props; if (!stripe || !elements) { // Stripe.js has not yet loaded. // Make sure to disable form submission until Stripe.js has loaded. return; } const result = await stripe.confirmPayment({ //`Elements` instance that was used to create the Payment Element elements, confirmParams: { return_url: "https://example.com/order/123/complete", }, }); if (result.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`. } }; render() { return ( <form onSubmit={this.handleSubmit}> <PaymentElement /> <button disabled={!this.props.stripe}>Submit</button> </form> ); } } export default function InjectedCheckoutForm() { return ( <ElementsConsumer> {({stripe, elements}) => ( <CheckoutForm stripe={stripe} elements={elements} /> )} </ElementsConsumer> ) }
prop
description

children

required ({elements, stripe}) => ReactNode

This component takes a function as child. The function that you provide will be called with the Elements object that is managing your Element components and the Stripe object that you passed to <Elements>.

Note that if you pass a Promise to the Elements provider and the Promise has not yet resolved, then stripe and elements will be null.

Customization and styling

Why iframes?

We recognize that the use of iframes makes styling an Element more difficult, but they shift the burden of securely handling payment data to Stripe and provide an easy way to keep your site compliant with industry regulation.

Each element is actually mounted in an iframe under the hood. Because of this, Elements are unlikely to work with any existing styling and component frameworks that you may have. Despite this, you are still able to fully configure Elements to seamlessly match the design of your site. Fully 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 more.

Customer location
Size
Theme
The demo displays Google Pay or Apple Pay only on their corresponding platform if you have an active card associated with the account.

Next steps

Build an integration with React Stripe.js and Elements.

  • Accept a payment
  • Adding the Payment Request Button
  • Learn about the Elements Appearance API
  • Stripe.js reference
Was this page helpful?
Questions? Contact us.
View developer tutorials on YouTube.
Check out our product changelog.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Setup
Elements provider
Element components
useElements hook
useStripe hook
ElementsConsumer
Customization and styling
Next steps
Stripe Shell
Test mode
▗▄ ▄▟█ █▀▀ ▗▟████▙▖ ██████ ███▗▟█ ███ ███▗▟██▙▖ ▗▟█████▙▖ ███▖ ▀▀ ███ ███▀▀▀ ███ ███▀ ███ ███ ███ ▝▜████▙▖ ███ ███ ███ ███ ███ █████████ ▄▄ ▝███ ███ ▄ ███ ███ ███▄ ███ ███ ▄▄ ▝▜████▛▘ ▝▜███▛ ███ ███ ███▝▜██▛▘ ▝▜█████▛▘ ███ ▀▘
Welcome to the Stripe Shell! This is a graphical user interface of the Stripe CLI. You can use it to discover webhook events and manage your Stripe resources. By pressing ctrl + ` you can toggle it open from any page within the Stripe documentation. - View supported commands: - Listen for webhook events: - Trigger webhook events: - Call Stripe APIs: stripe [api resource] [api operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$