## AddressElement

Use the `AddressElement` from `@stripe/react-stripe-js` to collect local and international billing and shipping addresses.

The component must be rendered inside an [Elements Provider](/js/react_stripe_js/elements/elements_provider.md).

### Props

- `id` (string)
  Sets the DOM `id` attribute on the rendered Element container. Use this to
target the Element for styling or testing.

- `className` (string)
  Applies custom CSS classes to the Element container.

- `options` (object) **required**
  Options for creating the Address Element.

  - `mode` ('shipping' | 'billing') **required**
    Specify which mode you would like to use Address Element for.

When `shipping` mode is used with the Payment Element and Link Authentication Element, it will automatically pass shipping information when confirming Payment Intent or Setup Intent.

When `billing` mode is used with the Payment Element, it will automatically pass the billing information when confirming Payment Intent or Setup Intent.

  - `autocomplete` (object)
    By default, the Address Element will have autocomplete enabled with Stripe provided Google Maps API key for certain countries if any of the following condition is met:
* If Payment Element is mounted in the same elements group as Address Element in a single page application.
* If the Address Element is used in an active Link session.

[Contact Legal before editing or deleting the Google Maps autocomplete callout]: #

By using autocomplete, you agree to comply with the [Google Maps Platform Acceptable Use Policy](https://cloud.google.com/maps-platform/terms/aup). If you violate this policy, we might disable autocomplete, or take any other action as necessary.

You can customize the autocomplete setting with this option.

    - `mode` (‘automatic’ | ‘disabled’ | ‘google_maps_api’) **required**
      Specify `disabled` to disable autocomplete in the Address Element.

Specify `google_maps_api` to enable [Google Maps API](https://developers.google.com/maps/documentation/javascript/places) with your own key. It will only be used when Stripe provided Google Maps API key is not available.

The default setting is `automatic`, where we’ll support autocomplete when possible.

    - `apiKey` (string)
      Specify your own [Google Maps API key](https://developers.google.com/maps/documentation/javascript/places#add-places-api-to-the-api-keys-api-restrictions-list) with it.

**Only needs to be passed in when `autocomplete.mode` is set to `google_maps_api`.**

  - `allowedCountries` (array)
    By default, the Address Element will display all countries for selection.

You can specify which countries are displayed in the Address Element with a list of two-letter country codes.
If only one country is specified, the country field will not display.

  - `blockPoBox` (boolean)
    By default, PO boxes are considered a valid address type.

You can override this to invalidate PO Boxes.

  - `contacts` (array)
    An array of [Contact](/js/appendix/contact_object.md) objects that can be displayed as saved addresses
in the Address Element. The first contact will be automatically selected.

If using a [CustomerSession](/api/customer_sessions.md), Address Element will ignore contacts
and render saved billing addresses instead.

  - `defaultValues` (object)
    Provide the initial information that will be displayed in the Address Element.
The form will render with empty fields if not provided.

    - `name` (string)
      Provide the initial full name or organization name.

    - `firstName` (string)
      Provide the initial first name.
The [display.name](/js/elements_object/create_address_element.md#address_element_create-options-display-name) option must be set to `split` if this property is specified.

    - `lastName` (string)
      Provide the initial last name.
The [display.name](/js/elements_object/create_address_element.md#address_element_create-options-display-name) option must be set to `split` if this property is specified.

    - `phone` (string)
      Provide the initial phone number value.
The [fields.phone](/js/elements_object/create_address_element.md#address_element_create-options-fields-phone) option must be set to `always` if this property is specified.

    - `address` (object)
      Provide the initial address details.

      - `line1` (string)

      - `line2` (string)

      - `city` (string)

      - `state` (string)

      - `postal_code` (string)

      - `country` (string) **required**

  - `fields` (object)
    By default, the Address Element will collect all the necessary information needed for an address.
In some cases, it might be necessary to collect other types of information. You can specify other types of fields to render
in the form with this option.

    - `phone` ('always' | 'auto' | 'never')
      Specify `always` to enable phone number collection in the Address Element.
Only collect phone numbers if you need them for the transaction. Default is `auto`.

  - `validation` (object)
    By default, the Address Element will enforce preset validation for each field.
You can customize the settings by using this option.

    - `phone` (object)

      - `required` ('always' | 'auto' | 'never')
        Specify `always` to make phone number a required field.
The [fields.phone](/js/elements_object/create_address_element.md#address_element_create-options-fields-phone) option must be set to `always` if this property is specified.
Default is `auto`.

  - `display` (object)
    You can customize how certain fields are displayed.

    - `name` ('full' | 'split' | 'organization')
      By default, the Address Element will display a full name field.
Specify 'split' to display a first name field and a last name field.
Specify 'organization' to display an organization field.

- `onChange` (function)
  Callback called when any value in the [change event payload](/js/element/events/on_change?type=addressElement.md#element_on_change-handler) changes.

- `onReady` (function)
  Callback called once the Element is fully rendered.
Recieves the [ready event payload](/js/element/events/on_ready.md#element_on_ready-handler).

- `onBlur` (function)
  Callback called when the Element loses focus.

- `onFocus` (function)
  Callback called when the Element receives focus.

- `onEscape` (function)
  Callback called when the escape key is pressed within the Element.

- `onLoaderStart` (function)
  Callback called right before Stripe displays the Element skeleton loader.
Receives the Element instance as its only argument.

- `onLoadError` (function)
  Callback called when the Element fails to load.

### Render AddressElement

```jsx
import React from 'react';
import {Elements, AddressElement} from '@stripe/react-stripe-js';
import {loadStripe} from '@stripe/stripe-js';

const stripePromise = loadStripe('{TEST_PUBLISHABLE_KEY}');

export const App = ({clientSecret}) => (
  <Elements stripe={stripePromise} options={{clientSecret}}>
    <AddressElement options={{mode: 'shipping'}} />
  </Elements>
);
```