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 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
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
.
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(
); 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> ); };'pk_test_TYooMQauvdEDq54NiTphI7jx'
prop | description |
---|---|
| required A Stripe object or a You can also pass in |
| optional Optional Elements configuration options. See available options. To create Payment Elements, you must include the Intent’s Because props are immutable, you can’t change |
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.
import {PaymentElement} from '@stripe/react-stripe-js'; const CheckoutForm = () => { return ( <form> <PaymentElement /> <button>Submit</button> </form> ); }; export default CheckoutForm;
prop | description |
---|---|
| optional Passes through to the Element’s container. |
| optional Passes through to the Element’s container. |
| optional An object containing Element configuration options. See available options for the Payment Element or available options for individual payment method Elements. |
| optional Triggered when the Element loses focus. |
| optional 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. |
| optional Triggered by the For more information, refer to the Stripe.js reference. |
| optional Triggered when the escape key is pressed within an Element. For more information, refer to the Stripe.js reference. |
| optional Triggered when the Element receives focus. |
| optional Triggered when the Element fails to load. This event is only emitted from the For more information, refer to the Stripe.js reference. |
| optional Triggered when the loader UI is mounted to the DOM and ready to be displayed. This event is only emitted from the For more information, refer to the Stripe.js reference. |
| optional Triggered when the Element is fully rendered and can accept imperative |
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 |
---|---|
AddressElement | Collects address details for 236+ regional formats. See the Address Element docs. |
AfterpayClearpayMessageElement | Displays installments messaging for Afterpay payments. |
AuBankAccountElement | Collects Australian bank account information (BSB and account number) for use with BECS Direct Debit payments. |
CardCvcElement | Collects the card‘s CVC number. |
CardElement | A flexible single-line input that collects all necessary card details. |
CardExpiryElement | Collects the card‘s expiration date. |
CardNumberElement | Collects the card number. |
ExpressCheckoutElement | Allows 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. |
FpxBankElement | The customer’s bank, for use with FPX payments. |
IbanElement | The International Bank Account Number (IBAN). Available for SEPA countries. |
IdealBankElement | The customer’s bank, for use with iDEAL payments. |
LinkAuthenticationElement | Collects email addresses and allows users to log in to Link. See the Link Authentication Element docs. |
PaymentElement | Collects payment details for 25+ payment methods from around the globe. See the Payment Element docs. |
PaymentRequestButtonElement | An 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
.
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
.
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.
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> ) }
prop | description |
---|---|
| required 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 |
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 more.
Next steps
Build an integration with React Stripe.js and Elements.