0
# Address and Contact Elements
1

2
Elements for collecting customer address, shipping, and contact information. These elements provide standardized address collection with built-in validation and formatting.
3

4
## Capabilities
5

6
### AddressElement
7

8
Comprehensive address collection element with automatic formatting and validation for international addresses.
9

10
```typescript { .api }
11
/**
12
 * Address collection element with international support
13
 * @param props - Address element configuration props
14
 * @returns JSX element for address collection
15
 */
16
function AddressElement(props: AddressElementProps): JSX.Element;
17

18
interface AddressElementProps extends ElementProps {
19
  /** Configuration options for the Address Element - REQUIRED */
20
  options: StripeAddressElementOptions;
21
  /** Triggered when data exposed by this Element is changed */
22
  onChange?: (event: StripeAddressElementChangeEvent) => any;
23
  /** Triggered when the Element is fully rendered and can accept focus */
24
  onReady?: (element: StripeAddressElement) => any;
25
  /** Triggered when the escape key is pressed within the Element */
26
  onEscape?: () => any;
27
  /** Triggered when the Element fails to load */
28
  onLoadError?: (event: {elementType: 'address'; error: StripeError}) => any;
29
  /** Triggered when the loader UI is mounted to the DOM */
30
  onLoaderStart?: (event: {elementType: 'address'}) => any;
31
}
32

33
interface StripeAddressElementOptions {
34
  /** Address collection mode */
35
  mode?: 'shipping' | 'billing';
36
  /** Whether to allow PO Boxes */
37
  allowedCountries?: string[];
38
  /** Block PO Box addresses */
39
  blockPoBox?: boolean;
40
  /** Fields to collect */
41
  fields?: {
42
    phone?: 'auto' | 'always' | 'never';
43
  };
44
  /** Address validation options */
45
  validation?: {
46
    mode?: 'auto' | 'always' | 'never';
47
  };
48
  /** Default values */
49
  defaultValues?: {
50
    name?: string;
51
    address?: {
52
      line1?: string;
53
      line2?: string;
54
      city?: string;
55
      state?: string;
56
      postal_code?: string;
57
      country?: string;
58
    };
59
    phone?: string;
60
  };
61
  /** Autocomplete configuration */
62
  autocomplete?: {
63
    mode?: 'automatic' | 'disabled';
64
  };
65
}
66
```
67

68
**Usage Examples:**
69

70
```typescript
71
import React, { useState } from 'react';
72
import { AddressElement, useStripe, useElements } from '@stripe/react-stripe-js';
73

74
const ShippingForm = () => {
75
  const stripe = useStripe();
76
  const elements = useElements();
77
  const [addressComplete, setAddressComplete] = useState(false);
78
  const [addressData, setAddressData] = useState(null);
79

80
  const handleAddressChange = (event) => {
81
    setAddressComplete(event.complete);
82
    if (event.complete) {
83
      setAddressData(event.value);
84
    }
85
  };
86

87
  const handleSubmit = async (event) => {
88
    event.preventDefault();
89

90
    if (!stripe || !elements || !addressComplete) return;
91

92
    const address = elements.getElement(AddressElement);
93
    
94
    // Get the address data
95
    const {error, complete, value} = await address.getValue();
96
    
97
    if (error) {
98
      console.log('[Address error]', error);
99
    } else if (complete) {
100
      console.log('[Address]', value);
101
      // Use address data in payment or shipping
102
    }
103
  };
104

105
  return (
106
    <form onSubmit={handleSubmit}>
107
      <h3>Shipping Address</h3>
108
      <AddressElement
109
        options={{
110
          mode: 'shipping',
111
          allowedCountries: ['US', 'CA', 'GB', 'AU'],
112
          fields: {
113
            phone: 'always'
114
          },
115
          validation: {
116
            mode: 'auto'
117
          },
118
          defaultValues: {
119
            name: 'Jenny Rosen',
120
            address: {
121
              country: 'US'
122
            }
123
          }
124
        }}
125
        onChange={handleAddressChange}
126
        onReady={() => console.log('AddressElement ready')}
127
      />
128
      <button disabled={!stripe || !addressComplete}>
129
        Continue to Payment
130
      </button>
131
    </form>
132
  );
133
};
134

135
// Billing address variant
136
const BillingAddressForm = () => (
137
  <AddressElement
138
    options={{
139
      mode: 'billing',
140
      fields: {
141
        phone: 'never'
142
      },
143
      blockPoBox: true
144
    }}
145
    onChange={(event) => {
146
      if (event.complete) {
147
        console.log('Billing address complete:', event.value);
148
      }
149
    }}
150
  />
151
);
152
```
153

154
### LinkAuthenticationElement
155

156
Link authentication element for Stripe Link login and account creation.
157

158
```typescript { .api }
159
/**
160
 * Link authentication element for Stripe Link integration
161
 * @param props - Link authentication element configuration props
162
 * @returns JSX element for Link authentication
163
 */
164
function LinkAuthenticationElement(props: LinkAuthenticationElementProps): JSX.Element;
165

166
interface LinkAuthenticationElementProps extends ElementProps {
167
  /** Configuration options for the Link Authentication Element */
168
  options?: StripeLinkAuthenticationElementOptions;
169
  /** Triggered when data exposed by this Element is changed */
170
  onChange?: (event: StripeLinkAuthenticationElementChangeEvent) => any;
171
  /** Triggered when the Element is fully rendered and can accept focus */
172
  onReady?: (element: StripeLinkAuthenticationElement) => any;
173
  /** Triggered when the escape key is pressed within the Element */
174
  onEscape?: () => any;
175
  /** Triggered when the Element fails to load */
176
  onLoadError?: (event: {elementType: 'linkAuthentication'; error: StripeError}) => any;
177
  /** Triggered when the loader UI is mounted to the DOM */
178
  onLoaderStart?: (event: {elementType: 'linkAuthentication'}) => any;
179
}
180

181
interface StripeLinkAuthenticationElementOptions {
182
  /** Default email value */
183
  defaultValues?: {
184
    email?: string;
185
  };
186
}
187
```
188

189
**Usage Examples:**
190

191
```typescript
192
import React, { useState } from 'react';
193
import { LinkAuthenticationElement, PaymentElement } from '@stripe/react-stripe-js';
194

195
const LinkPaymentForm = () => {
196
  const [email, setEmail] = useState('');
197
  const [linkAccount, setLinkAccount] = useState(null);
198

199
  const handleLinkChange = (event) => {
200
    setEmail(event.value.email);
201
    
202
    if (event.complete) {
203
      // User has authenticated with Link
204
      setLinkAccount(event.value);
205
      console.log('Link authenticated:', event.value);
206
    }
207
  };
208

209
  return (
210
    <form>
211
      <LinkAuthenticationElement
212
        options={{
213
          defaultValues: {
214
            email: 'customer@example.com'
215
          }
216
        }}
217
        onChange={handleLinkChange}
218
        onReady={() => console.log('LinkAuthenticationElement ready')}
219
      />
220
      
221
      {/* PaymentElement will automatically integrate with Link if authenticated */}
222
      <PaymentElement />
223
      
224
      <button disabled={!email}>
225
        Pay {linkAccount ? 'with Link' : 'Now'}
226
      </button>
227
    </form>
228
  );
229
};
230
```
231

232
### TaxIdElement
233

234
Tax ID collection element for business tax identification numbers (requires beta access).
235

236
```typescript { .api }
237
/**
238
 * Tax ID collection element for business identification
239
 * Requires beta access - contact Stripe support for more information
240
 * @param props - Tax ID element configuration props
241
 * @returns JSX element for tax ID collection
242
 */
243
function TaxIdElement(props: TaxIdElementProps): JSX.Element;
244

245
interface TaxIdElementProps extends ElementProps {
246
  /** Configuration options for the Tax ID Element */
247
  options: StripeTaxIdElementOptions;
248
  /** Triggered when data exposed by this Element is changed */
249
  onChange?: (event: StripeTaxIdElementChangeEvent) => any;
250
  /** Triggered when the Element is fully rendered and can accept focus */
251
  onReady?: (element: StripeTaxIdElement) => any;
252
  /** Triggered when the escape key is pressed within the Element */
253
  onEscape?: () => any;
254
  /** Triggered when the Element fails to load */
255
  onLoadError?: (event: {elementType: 'taxId'; error: StripeError}) => any;
256
  /** Triggered when the loader UI is mounted to the DOM */
257
  onLoaderStart?: (event: {elementType: 'taxId'}) => any;
258
}
259

260
interface StripeTaxIdElementOptions {
261
  /** Supported tax ID types */
262
  supportedTypes?: Array<{
263
    type: string;
264
    country: string;
265
  }>;
266
  /** Default values */
267
  defaultValues?: {
268
    type?: string;
269
    value?: string;
270
  };
271
}
272
```
273

274
**Usage Examples:**
275

276
```typescript
277
import React, { useState } from 'react';
278
import { TaxIdElement } from '@stripe/react-stripe-js';
279

280
const BusinessTaxForm = () => {
281
  const [taxIdComplete, setTaxIdComplete] = useState(false);
282
  const [taxIdData, setTaxIdData] = useState(null);
283

284
  const handleTaxIdChange = (event) => {
285
    setTaxIdComplete(event.complete);
286
    if (event.complete) {
287
      setTaxIdData(event.value);
288
    }
289
  };
290

291
  return (
292
    <form>
293
      <h3>Business Tax Information</h3>
294
      <TaxIdElement
295
        options={{
296
          supportedTypes: [
297
            { type: 'us_ein', country: 'US' },
298
            { type: 'eu_vat', country: 'DE' },
299
            { type: 'ca_bn', country: 'CA' }
300
          ],
301
          defaultValues: {
302
            type: 'us_ein'
303
          }
304
        }}
305
        onChange={handleTaxIdChange}
306
        onReady={() => console.log('TaxIdElement ready')}
307
      />
308
      {taxIdData && (
309
        <div>
310
          Tax ID: {taxIdData.type} - {taxIdData.value}
311
        </div>
312
      )}
313
      <button disabled={!taxIdComplete}>
314
        Submit Business Information
315
      </button>
316
    </form>
317
  );
318
};
319
```
320

321
### ShippingAddressElement (Deprecated)
322

323
Legacy shipping address element - use AddressElement with mode: 'shipping' instead.
324

325
```typescript { .api }
326
/**
327
 * @deprecated Use AddressElement with mode: 'shipping' instead
328
 * Legacy shipping address element
329
 */
330
function ShippingAddressElement(props: ShippingAddressElementProps): JSX.Element;
331

332
interface ShippingAddressElementProps extends ElementProps {
333
  options?: StripeShippingAddressElementOptions;
334
  onChange?: (event: StripeShippingAddressElementChangeEvent) => any;
335
  onReady?: (element: StripeShippingAddressElement) => any;
336
  onEscape?: () => any;
337
  onLoadError?: (event: {elementType: 'shippingAddress'; error: StripeError}) => any;
338
  onLoaderStart?: (event: {elementType: 'shippingAddress'}) => any;
339
}
340
```
341

342
## Element Event Types
343

344
```typescript { .api }
345
interface StripeAddressElementChangeEvent {
346
  elementType: 'address';
347
  empty: boolean;
348
  complete: boolean;
349
  isValidAddress?: boolean;
350
  value: {
351
    name: string;
352
    address: {
353
      line1: string;
354
      line2?: string;
355
      city: string;
356
      state: string;
357
      postal_code: string;
358
      country: string;
359
    };
360
    phone?: string;
361
  };
362
}
363

364
interface StripeLinkAuthenticationElementChangeEvent {
365
  elementType: 'linkAuthentication';
366
  empty: boolean;
367
  complete: boolean;
368
  value: {
369
    email: string;
370
  };
371
}
372

373
interface StripeTaxIdElementChangeEvent {
374
  elementType: 'taxId';
375
  empty: boolean;
376
  complete: boolean;
377
  value: {
378
    type: string;
379
    value: string;
380
  };
381
}
382
```
383

384
## Address Validation and Formatting
385

386
```typescript
387
// Address validation example
388
const ValidatedAddressForm = () => {
389
  const [validationResult, setValidationResult] = useState(null);
390

391
  const handleAddressChange = (event) => {
392
    if (event.complete) {
393
      // Address is complete, validation results available
394
      setValidationResult({
395
        isValid: event.isValidAddress,
396
        address: event.value.address,
397
        suggestions: event.value.suggestions || []
398
      });
399
    }
400
  };
401

402
  return (
403
    <div>
404
      <AddressElement
405
        options={{
406
          mode: 'shipping',
407
          validation: {
408
            mode: 'auto' // Automatically validate addresses
409
          },
410
          autocomplete: {
411
            mode: 'automatic' // Enable address autocomplete
412
          }
413
        }}
414
        onChange={handleAddressChange}
415
      />
416
      
417
      {validationResult && !validationResult.isValid && (
418
        <div className="address-warning">
419
          Address may be invalid. Please verify the details.
420
        </div>
421
      )}
422
    </div>
423
  );
424
};
425
```