0
# React Stripe.js
1

2
React Stripe.js provides official React components and hooks for Stripe.js and Elements, enabling developers to build secure payment interfaces in React applications. It offers a comprehensive set of Element components for different payment methods, context providers for managing Stripe instances, and React hooks for accessing payment functionality.
3

4
## Package Information
5

6
- **Package Name**: @stripe/react-stripe-js
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @stripe/react-stripe-js @stripe/stripe-js`
10

11
## Core Imports
12

13
```typescript
14
import {
15
  Elements,
16
  useStripe,
17
  useElements,
18
  PaymentElement,
19
  CardElement
20
} from "@stripe/react-stripe-js";
21
```
22

23
For checkout-specific features:
24

25
```typescript
26
import {
27
  CheckoutProvider,
28
  useCheckout,
29
  BillingAddressElement,
30
  ShippingAddressElement
31
} from "@stripe/react-stripe-js/checkout";
32
```
33

34
CommonJS:
35

36
```javascript
37
const {
38
  Elements,
39
  useStripe,
40
  useElements,
41
  PaymentElement,
42
  CardElement
43
} = require("@stripe/react-stripe-js");
44
```
45

46
## Basic Usage
47

48
```typescript
49
import React, { useState } from 'react';
50
import { loadStripe } from '@stripe/stripe-js';
51
import {
52
  Elements,
53
  PaymentElement,
54
  useStripe,
55
  useElements
56
} from '@stripe/react-stripe-js';
57

58
const stripePromise = loadStripe('pk_test_...');
59

60
const CheckoutForm = () => {
61
  const stripe = useStripe();
62
  const elements = useElements();
63
  const [isLoading, setIsLoading] = useState(false);
64

65
  const handleSubmit = async (event) => {
66
    event.preventDefault();
67
    
68
    if (!stripe || !elements) return;
69
    
70
    setIsLoading(true);
71
    
72
    const { error } = await stripe.confirmPayment({
73
      elements,
74
      confirmParams: {
75
        return_url: 'https://example.com/order/123/complete',
76
      },
77
    });
78
    
79
    if (error) {
80
      console.error(error.message);
81
    }
82
    
83
    setIsLoading(false);
84
  };
85

86
  return (
87
    <form onSubmit={handleSubmit}>
88
      <PaymentElement />
89
      <button disabled={!stripe || isLoading}>
90
        {isLoading ? 'Processing...' : 'Pay now'}
91
      </button>
92
    </form>
93
  );
94
};
95

96
const App = () => (
97
  <Elements stripe={stripePromise} options={{ clientSecret: 'pi_...' }}>
98
    <CheckoutForm />
99
  </Elements>
100
);
101
```
102

103
## Architecture
104

105
React Stripe.js is built around several key architectural patterns:
106

107
- **Context Providers**: `Elements` and `EmbeddedCheckoutProvider` manage Stripe instances and configuration
108
- **React Hooks**: `useStripe` and `useElements` provide access to Stripe functionality within components
109
- **Element Components**: Pre-built React components wrapping Stripe Elements for specific payment methods
110
- **TypeScript Integration**: Full type safety with comprehensive TypeScript definitions
111
- **Server-Side Rendering**: Built-in SSR support with automatic client/server detection
112
- **Checkout Flow Support**: Specialized checkout components and providers for streamlined payment flows
113

114
## Capabilities
115

116
### Core Providers and Hooks
117

118
Essential React context providers and hooks for integrating Stripe functionality into React applications.
119

120
```typescript { .api }
121
function Elements(props: ElementsProps): JSX.Element;
122

123
interface ElementsProps {
124
  stripe: PromiseLike<Stripe | null> | Stripe | null;
125
  options?: StripeElementsOptions;
126
  children: ReactNode;
127
}
128

129
function useStripe(): Stripe | null;
130
function useElements(): StripeElements | null;
131
```
132

133
[Core Providers and Hooks](./core-providers-hooks.md)
134

135
### Payment Elements
136

137
Modern payment elements supporting multiple payment methods with unified interfaces.
138

139
```typescript { .api }
140
function PaymentElement(props: PaymentElementProps): JSX.Element;
141
function ExpressCheckoutElement(props: ExpressCheckoutElementProps): JSX.Element;
142
function PaymentRequestButtonElement(props: PaymentRequestButtonElementProps): JSX.Element;
143

144
interface PaymentElementProps extends ElementProps {
145
  options?: StripePaymentElementOptions;
146
  onChange?: (event: StripePaymentElementChangeEvent) => any;
147
  onReady?: (element: StripePaymentElement) => any;
148
  onEscape?: () => any;
149
  onLoadError?: (event: {elementType: 'payment'; error: StripeError}) => any;
150
  onLoaderStart?: (event: {elementType: 'payment'}) => any;
151
}
152
```
153

154
[Payment Elements](./payment-elements.md)
155

156
### Card Elements
157

158
Individual card input elements for granular control over payment form layout.
159

160
```typescript { .api }
161
function CardElement(props: CardElementProps): JSX.Element;
162
function CardNumberElement(props: CardNumberElementProps): JSX.Element;
163
function CardExpiryElement(props: CardExpiryElementProps): JSX.Element;
164
function CardCvcElement(props: CardCvcElementProps): JSX.Element;
165

166
interface CardElementProps extends ElementProps {
167
  options?: StripeCardElementOptions;
168
  onChange?: (event: StripeCardElementChangeEvent) => any;
169
  onReady?: (element: StripeCardElement) => any;
170
  onEscape?: () => any;
171
  onNetworksChange?: (event: {elementType: 'card'}) => any;
172
  onLoadError?: (event: {elementType: 'card'; error: StripeError}) => any;
173
}
174
```
175

176
[Card Elements](./card-elements.md)
177

178
### Bank Payment Elements
179

180
Elements for region-specific bank payment methods and direct bank transfers.
181

182
```typescript { .api }
183
function IbanElement(props: IbanElementProps): JSX.Element;
184
function FpxBankElement(props: FpxBankElementProps): JSX.Element;
185
function IdealBankElement(props: IdealBankElementProps): JSX.Element;
186
function P24BankElement(props: P24BankElementProps): JSX.Element;
187
function EpsBankElement(props: EpsBankElementProps): JSX.Element;
188
function AuBankAccountElement(props: AuBankAccountElementProps): JSX.Element;
189

190
interface IbanElementProps extends ElementProps {
191
  options?: StripeIbanElementOptions;
192
  onChange?: (event: StripeIbanElementChangeEvent) => any;
193
  onReady?: (element: StripeIbanElement) => any;
194
  onEscape?: () => any;
195
}
196
```
197

198
[Bank Payment Elements](./bank-elements.md)
199

200
### Address and Contact Elements
201

202
Elements for collecting customer address, shipping, and contact information.
203

204
```typescript { .api }
205
function AddressElement(props: AddressElementProps): JSX.Element;
206
function LinkAuthenticationElement(props: LinkAuthenticationElementProps): JSX.Element;
207
function TaxIdElement(props: TaxIdElementProps): JSX.Element;
208

209
interface AddressElementProps extends ElementProps {
210
  options?: StripeAddressElementOptions;
211
  onChange?: (event: StripeAddressElementChangeEvent) => any;
212
  onReady?: (element: StripeAddressElement) => any;
213
  onEscape?: () => any;
214
  onLoadError?: (event: {elementType: 'address'; error: StripeError}) => any;
215
  onLoaderStart?: (event: {elementType: 'address'}) => any;
216
}
217
```
218

219
[Address and Contact Elements](./address-elements.md)
220

221
### Message Elements
222

223
Elements for displaying financing options and payment method messaging to customers.
224

225
```typescript { .api }
226
function PaymentMethodMessagingElement(props: PaymentMethodMessagingElementProps): JSX.Element;
227
function AffirmMessageElement(props: AffirmMessageElementProps): JSX.Element;
228
function AfterpayClearpayMessageElement(props: AfterpayClearpayMessageElementProps): JSX.Element;
229

230
interface PaymentMethodMessagingElementProps extends ElementProps {
231
  options?: StripePaymentMethodMessagingElementOptions;
232
  onReady?: (element: StripePaymentMethodMessagingElement) => any;
233
  onEscape?: () => any;
234
  onLoadError?: (event: {elementType: 'paymentMethodMessaging'; error: StripeError}) => any;
235
  onLoaderStart?: (event: {elementType: 'paymentMethodMessaging'}) => any;
236
}
237
```
238

239
[Message Elements](./message-elements.md)
240

241
### Embedded Checkout
242

243
Complete embedded checkout solution for streamlined payment experiences.
244

245
```typescript { .api }
246
function EmbeddedCheckoutProvider(props: EmbeddedCheckoutProviderProps): JSX.Element;
247
function EmbeddedCheckout(props: EmbeddedCheckoutProps): JSX.Element;
248

249
interface EmbeddedCheckoutProviderProps {
250
  stripe: PromiseLike<Stripe | null> | Stripe | null;
251
  options: EmbeddedCheckoutOptions;
252
  children: ReactNode;
253
}
254

255
interface EmbeddedCheckoutProps {
256
  id?: string;
257
  className?: string;
258
}
259
```
260

261
[Embedded Checkout](./embedded-checkout.md)
262

263
### Checkout Flow Components
264

265
Specialized components and providers for optimized checkout experiences.
266

267
```typescript { .api }
268
function CheckoutProvider(props: CheckoutProviderProps): JSX.Element;
269
function useCheckout(): CheckoutState;
270
function BillingAddressElement(props: BillingAddressElementProps): JSX.Element;
271
function ShippingAddressElement(props: ShippingAddressElementProps): JSX.Element;
272
function CurrencySelectorElement(props: CurrencySelectorElementProps): JSX.Element;
273

274
type CheckoutState =
275
  | {type: 'loading'}
276
  | {type: 'success'; checkout: CheckoutValue}
277
  | {type: 'error'; error: {message: string}};
278
```
279

280
[Checkout Flow Components](./checkout-components.md)
281

282
## Common Types
283

284
```typescript { .api }
285
interface ElementProps {
286
  id?: string;
287
  className?: string;
288
  onBlur?: (event: {elementType: StripeElementType}) => any;
289
  onFocus?: (event: {elementType: StripeElementType}) => any;
290
}
291

292
interface StripeElementsOptions {
293
  clientSecret?: string;
294
  appearance?: StripeElementsAppearance;
295
  fonts?: StripeElementsFonts;
296
  locale?: string;
297
  loader?: 'auto' | 'never' | 'always';
298
}
299

300
interface StripeElementsAppearance {
301
  theme?: 'stripe' | 'night' | 'flat';
302
  variables?: Record<string, string>;
303
  rules?: Record<string, Record<string, string>>;
304
}
305

306
interface StripeElementsFonts {
307
  family?: string;
308
  src?: string;
309
  display?: string;
310
  style?: string;
311
  unicodeRange?: string;
312
  weight?: string;
313
}
314

315
type StripeElementType = 
316
  | 'card' | 'cardNumber' | 'cardExpiry' | 'cardCvc'
317
  | 'payment' | 'expressCheckout' | 'paymentRequestButton'
318
  | 'iban' | 'fpxBank' | 'idealBank' | 'p24Bank' | 'epsBank' | 'auBankAccount'
319
  | 'address' | 'shippingAddress' | 'linkAuthentication' | 'taxId'
320
  | 'paymentMethodMessaging' | 'affirmMessage' | 'afterpayClearpayMessage';
321

322
interface EmbeddedCheckoutOptions {
323
  clientSecret?: string;
324
  fetchClientSecret?: () => Promise<string>;
325
  onComplete?: () => void;
326
  onError?: (error: {message: string}) => void;
327
}
328

329
type StripeError = {
330
  type: string;
331
  code?: string;
332
  message: string;
333
  decline_code?: string;
334
  param?: string;
335
};
336
```