## The Address Element

The Address Element is
an embeddable component for collecting local and international billing and shipping addresses.

## Create the Address Element

This method creates an instance of the Address Element.

**NOTE**: If you are creating multiple instances of the Address Element, configuration of the checkbox to sync shipping and billing addresses exists in the creation of the [Elements](/js/elements_object/create.md#stripe_elements-options-syncAddressCheckbox) instance.

**Syntax:** `elements.create(...)`

- `type` ('address') **required**
  The type of Element being created, which is `address` in this case.

You can create multiple Address Elements, one of each mode, in a single Elements instance.

- `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.

### Create an Address Element

```js
// Create the Address Element in shipping mode
var shippingAddressElement = elements.create('address', {
  mode: 'shipping',
});

// Create the Address Element in billing mode
var billingAddressElement = elements.create('address', {
  mode: 'billing',
});
```

```es_next
// Create the Address Element in shipping mode
const shippingAddressElement = elements.create('address', {
  mode: 'shipping',
});

// Create the Address Element in billing mode
const billingAddressElement = elements.create('address', {
  mode: 'billing',
});
```

## Get an Address Element

This method retrieves a previously created Address Element.

`elements.getElement('address')` returns one of the following:

* An instance of an Address Element.
* `null`, when no Address Element has been created.

**Syntax:** `elements.getElement(...)`

- `type` ('address') **required**
  The type of Element being retrieved, which is `address` in this case.

- `options` (object)
  Options for retrieving the Address Element.

  - `mode` ('shipping' | 'billing')
    Required when using multiple Address Elements.

Specify which mode of the Address Element you would like to retrieve.

### Get an Address Element

```js
var addressElement = elements.getElement('address');
```

```es_next
const addressElement = elements.getElement('address');
```

## Update an Address Element

Updates the options the [Address Element](/js/element/address_element.md)
was initialized with. Updates are merged into the existing configuration.

**Syntax:** `element.update(...)`

- `options` (object)
  Options for updating the Address Element.

  - `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`.

### Update an Address Element

```js
var addressElement = elements.getElement('address');

addressElement.update({
  validation: {
    phone: {
      required: 'never',
    },
  },
});
```

```es_next
const addressElement = elements.getElement('address');

addressElement.update({
  validation: {
    phone: {
      required: 'never',
    },
  },
});
```

## Get value from an Address Element

Validates and retrieves form values from an Address Element. If there are any input validation errors,
the errors will display by their respective fields.

`addressElement.getValue()` returns a promise. This promise will return an object with the following:

* `complete`, `true` if the value is well-formed and potentially complete.
  The `complete` value can be used to progressively disclose the next parts of your form or to enable form submission.
  It is not an indicator of whether a customer is done with their input—it only indicates that the Element contains a potentially complete, well-formed value.
  In many cases the customer could still add further input.
* `isNewAddress`, `true` if the Address Element is currently displaying the form collection view.
* `value`, an object containing the current address information. The `firstName` and
  `lastName` properties only appear if the `display.name` option is set to `split`.
  The `phone` property only appears if the `fields.phone` option is set to `always`.

**Syntax:** `element.getValue(...)`

### Get value from an Address Element

```js
var addressElement = elements.getElement('address');

addressElement.getValue()
.then(function(result) {
  if (result.complete) {
    // Allow user to proceed to the next step
    // Optionally, use value to store the address details
  }
})
```

```es_next
const addressElement = elements.getElement('address');
const {complete, value} = await addressElement.getValue();
if (complete) {
  // Allow user to proceed to the next step
  // Optionally store the address details with value
}
```