0
# Core Providers and Hooks
1

2
Essential React context providers and hooks for integrating Stripe functionality into React applications. These form the foundation for all Stripe payment integrations.
3

4
## Capabilities
5

6
### Elements Provider
7

8
The main context provider that manages the Stripe instance and Elements configuration throughout your React application.
9

10
```typescript { .api }
11
/**
12
 * React context provider for Stripe Elements
13
 * @param props - Elements configuration props
14
 * @returns JSX element wrapping child components with Elements context
15
 */
16
function Elements(props: ElementsProps): JSX.Element;
17

18
interface ElementsProps {
19
  /** Stripe instance or Promise resolving to Stripe instance */
20
  stripe: PromiseLike<Stripe | null> | Stripe | null;
21
  /** Configuration options for Elements */
22
  options?: StripeElementsOptions;
23
  /** Child components that will have access to Elements context */
24
  children: ReactNode;
25
}
26

27
interface StripeElementsOptions {
28
  /** Client secret for the payment intent or setup intent */
29
  clientSecret?: string;
30
  /** Appearance customization options */
31
  appearance?: StripeElementsAppearance;
32
  /** Custom fonts configuration */
33
  fonts?: StripeElementsFonts;
34
  /** Locale for displaying text */
35
  locale?: string;
36
  /** Controls when Elements are loaded */
37
  loader?: 'auto' | 'never' | 'always';
38
}
39
```
40

41
**Usage Examples:**
42

43
```typescript
44
import React from 'react';
45
import { loadStripe } from '@stripe/stripe-js';
46
import { Elements } from '@stripe/react-stripe-js';
47

48
const stripePromise = loadStripe('pk_test_...');
49

50
// Basic usage
51
const App = () => (
52
  <Elements stripe={stripePromise}>
53
    <PaymentForm />
54
  </Elements>
55
);
56

57
// With options
58
const AppWithOptions = () => (
59
  <Elements 
60
    stripe={stripePromise}
61
    options={{
62
      clientSecret: 'pi_...',
63
      appearance: {
64
        theme: 'stripe',
65
        variables: {
66
          colorPrimary: '#0570de',
67
        },
68
      },
69
      locale: 'en'
70
    }}
71
  >
72
    <PaymentForm />
73
  </Elements>
74
);
75

76
// SSR-safe with null stripe
77
const SSRApp = () => (
78
  <Elements stripe={null}>
79
    <PaymentForm />
80
  </Elements>
81
);
82
```
83

84
### useStripe Hook
85

86
React hook for accessing the Stripe instance from within components wrapped by Elements provider.
87

88
```typescript { .api }
89
/**
90
 * Hook to access Stripe instance from Elements context
91
 * @returns Stripe instance or null if not available
92
 */
93
function useStripe(): Stripe | null;
94
```
95

96
**Usage Examples:**
97

98
```typescript
99
import React from 'react';
100
import { useStripe } from '@stripe/react-stripe-js';
101

102
const PaymentComponent = () => {
103
  const stripe = useStripe();
104

105
  const handlePayment = async () => {
106
    if (!stripe) {
107
      console.error('Stripe has not loaded yet.');
108
      return;
109
    }
110

111
    // Use stripe instance for payment operations
112
    const {error, paymentIntent} = await stripe.confirmCardPayment(
113
      clientSecret,
114
      {
115
        payment_method: {
116
          card: cardElement,
117
          billing_details: {
118
            name: 'Jenny Rosen',
119
          },
120
        }
121
      }
122
    );
123
  };
124

125
  return (
126
    <button onClick={handlePayment} disabled={!stripe}>
127
      Pay Now
128
    </button>
129
  );
130
};
131
```
132

133
### useElements Hook
134

135
React hook for accessing the Elements instance from within components wrapped by Elements provider.
136

137
```typescript { .api }
138
/**
139
 * Hook to access Elements instance from Elements context
140
 * @returns StripeElements instance or null if not available
141
 */
142
function useElements(): StripeElements | null;
143
```
144

145
**Usage Examples:**
146

147
```typescript
148
import React from 'react';
149
import { useElements, useStripe } from '@stripe/react-stripe-js';
150

151
const PaymentForm = () => {
152
  const stripe = useStripe();
153
  const elements = useElements();
154

155
  const handleSubmit = async (event) => {
156
    event.preventDefault();
157

158
    if (!stripe || !elements) {
159
      return;
160
    }
161

162
    // Trigger form validation and wallet collection
163
    const {error: submitError} = await elements.submit();
164
    if (submitError) {
165
      console.error(submitError.message);
166
      return;
167
    }
168

169
    // Confirm payment
170
    const {error} = await stripe.confirmPayment({
171
      elements,
172
      confirmParams: {
173
        return_url: 'https://example.com/complete',
174
      },
175
    });
176
  };
177

178
  return (
179
    <form onSubmit={handleSubmit}>
180
      <PaymentElement />
181
      <button disabled={!stripe || !elements}>
182
        Submit
183
      </button>
184
    </form>
185
  );
186
};
187
```
188

189
### ElementsConsumer
190

191
Render prop component for accessing Elements context without hooks (useful for class components).
192

193
```typescript { .api }
194
/**
195
 * Render prop component for accessing Elements context
196
 * @param props - Consumer props with children render function
197
 * @returns Rendered result of children function
198
 */
199
function ElementsConsumer(props: ElementsConsumerProps): ReactNode;
200

201
interface ElementsConsumerProps {
202
  /** Render function receiving Elements context value */
203
  children: (props: ElementsContextValue) => ReactNode;
204
}
205

206
interface ElementsContextValue {
207
  /** Elements instance */
208
  elements: StripeElements | null;
209
  /** Stripe instance */
210
  stripe: Stripe | null;
211
}
212
```
213

214
**Usage Examples:**
215

216
```typescript
217
import React from 'react';
218
import { ElementsConsumer } from '@stripe/react-stripe-js';
219

220
class PaymentForm extends React.Component {
221
  render() {
222
    return (
223
      <ElementsConsumer>
224
        {({stripe, elements}) => (
225
          <form onSubmit={(e) => this.handleSubmit(e, stripe, elements)}>
226
            <PaymentElement />
227
            <button disabled={!stripe}>
228
              Pay Now
229
            </button>
230
          </form>
231
        )}
232
      </ElementsConsumer>
233
    );
234
  }
235

236
  handleSubmit = async (event, stripe, elements) => {
237
    event.preventDefault();
238
    
239
    if (!stripe || !elements) return;
240
    
241
    const {error} = await stripe.confirmPayment({
242
      elements,
243
      confirmParams: {
244
        return_url: 'https://example.com/complete',
245
      },
246
    });
247
    
248
    if (error) {
249
      console.error(error.message);
250
    }
251
  };
252
}
253
```
254

255
## Error Handling
256

257
All hooks will throw an error if used outside of an Elements provider:
258

259
```typescript
260
// This will throw an error
261
const MyComponent = () => {
262
  const stripe = useStripe(); // Error: Could not find Elements context
263
  return <div>Component</div>;
264
};
265

266
// Correct usage
267
const App = () => (
268
  <Elements stripe={stripePromise}>
269
    <MyComponent /> {/* Now useStripe() will work */}
270
  </Elements>
271
);
272
```
273

274
## TypeScript Integration
275

276
The hooks and providers are fully typed with proper TypeScript definitions:
277

278
```typescript
279
import { Stripe, StripeElements } from '@stripe/stripe-js';
280

281
const PaymentComponent: React.FC = () => {
282
  // These are properly typed
283
  const stripe: Stripe | null = useStripe();
284
  const elements: StripeElements | null = useElements();
285
  
286
  return <div>Payment Component</div>;
287
};
288
```