Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer resources
Overview
Versioning
Changelog
Upgrade your API version
Upgrade your SDK version
Essentials
SDKs
    Overview
    Server-side SDKs
    Mobile SDKs
    iOS SDK
    Android SDK
    React Native SDK
    Web SDKs
    ES Module Stripe.js
    React Stripe.js
    Terminal SDKs
    iOS SDK
    Android SDK
    React Native SDK
    Community
    Community SDKs
    Mobile migrations
    Migrate to iOS SDK 24
    Migrate to Android SDK 21
API
Testing
Stripe CLI
Sample projects
Tools
Workbench
Developers Dashboard
Stripe Shell
Stripe for Visual Studio Code
Features
Workflows
Event Destinations
Stripe health alertsFile uploads
AI solutions
Agent toolkit
Model Context Protocol
Security and privacy
Security
Stripebot web crawler
Privacy
Extend Stripe
Build Stripe apps
Use apps from Stripe
Partners
Partner ecosystem
Partner certification
HomeDeveloper resourcesSDKs

React Stripe.js reference

Learn about React components for Stripe.js and Stripe Elements.

See the code

If you 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 customisation details.

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

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 look at a sample integration.

Before you begin

This documentation 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 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

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

stripe

required Stripe | null | Promise<Stripe | null>

A Stripe object or a Promise resolving to a Stripe object. The easiest way to initialise a Stripe object is with the Stripe.js wrapper module. 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

optional Object

Optional Elements configuration options. See available options. To create Payment Elements, you must include the Intent’s clientSecret unless you render the element before creating the Intent.

Because props are immutable, you can’t change options after setting it. However, you can change the appearance of an element by calling the elements.update method.

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.jsx
import {PaymentElement} from '@stripe/react-stripe-js'; const CheckoutForm = () => { return ( <form> <PaymentElement /> <button>Submit</button> </form> ); }; export default CheckoutForm;
propdescription

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.

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.

You only receive these events from the payment, linkAuthentication, address, and expressCheckout Elements.

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, linkAuthentication, 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.

Available Element components

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

ComponentUsage
AddressElementCollects address details for 236+ regional formats. See the Address Element docs.
AfterpayClearpayMessageElementDisplays installments messaging for Afterpay payments.
AuBankAccountElementCollects Australian bank account information (BSB and account number) for use with BECS Direct Debit payments.
CardCvcElementCollects the card‘s CVC number.
CardElementA flexible single-line input that collects all necessary card details.
CardExpiryElementCollects the card‘s expiration date.
CardNumberElementCollects the card number.
ExpressCheckoutElementAllows you to accept card or wallet payments through one or more payment buttons, including Apple Pay, Google Pay, Link, or PayPal. See the Express Checkout Element docs.
FpxBankElementThe customer’s bank, for use with FPX payments.
IbanElementThe International Bank Account Number (IBAN). Available for SEPA countries.
IdealBankElementThe customer’s bank, for use with iDEAL payments.
LinkAuthenticationElementCollects email addresses and allows users to log in to Link. See the Link Authentication Element docs.
PaymentElementCollects payment details for 25+ payment methods from around the globe. See the Payment Element docs.
PaymentRequestButtonElementAn all-in-one checkout button backed by either Apple Pay or the Payment Request API. See the Payment Request Button docs.

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

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

CheckoutForm.jsx
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 hasn't 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> ) }; export default CheckoutForm;

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

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

CheckoutForm.jsx
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 hasn't 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> ) }; export default CheckoutForm;

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.jsx
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 hasn't 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> ) }
propdescription

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 hasn’t yet resolved, then stripe and elements will be null.

Customization and styling

Why iframes?

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

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. Customising Elements consists of responding to events and configuring Elements with the appearance option. The layout of each Element stays consistent, but you can modify colours, fonts, borders, padding, and more.

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.

  • Accept a payment
  • Accept a payment with the Express Checkout Element
  • Adding the Payment Request Button
  • Learn about the Elements Appearance API
  • Stripe.js reference
Was this page helpful?
YesNo
  • Need help? Contact Support.
  • Join our early access programme.
  • Check out our changelog.
  • Questions? Contact Sales.
  • LLM? Read llms.txt.
  • Powered by Markdoc