Address Element

The Address Element is an UI component for accepting complete addresses. Use it to collect shipping addresses, or when you need a complete billing address, such as for tax purposes.

(If you only need a single address field for verification—like the postal code in a card transaction—then you don’t need the Address Element. The Payment Element displays these fields automatically.)

Start with examples

To see the Address Element in action, start with one of these examples:

Create an Address Element

When you create an Address Element, specify whether to use it in shipping or billing mode.

const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

const appearance = { /* appearance */ };
const options = { mode: 'shipping' };
const elements = stripe.elements({ 
clientSecret
, appearance });
const addressElement = elements.create('address', options);
addressElement.mount('#address-element');

Use an address

The Address Element automatically works with the Payment or Pay Button Element. When a customer provides an address and a payment method, Stripe combines them into a single PaymentIntent with the address in the correct field.

Automatic behavior

The element’s default behavior depends on its mode.

const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

const appearance = { /* appearance */ };
const options = { mode: 'shipping' };
const elements = stripe.elements({ 
clientSecret
 });
const addressElement = elements.create('address', options);
const paymentElement = elements.create('payment');
addressElement.mount('#address-element');
paymentElement.mount('#payment-element');

Custom behavior

Normally, the Address Element’s default behavior is enough. But in a complex payment flow, you may need to write custom responses to the customer’s input. For information, see Listen for address input.

Autocomplete

The Address Element can autocomplete addresses for 25 countries. If your customer selects a supported country for their address, then they see the autocomplete options. These are the supported countries for autocomplete:

If you use the Address Element and the Payment Element together, Stripe enables autocomplete with no configuration required.

If you use the Address Element alone, you must use your own Google Maps API Places Library key, which is managed separately from your Stripe account. Pass the key in the autocomplete.apiKey option.

Autofill with Link

Link, Stripe’s one-click checkout tool, saves and autofills your customers’ payment and shipping information. When a returning Link customer authenticates, Stripe autofills their shipping information in the Address element.

To enable autofill, create all elements from the same Elements object, as in this example:

const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

const appearance = { /* appearance */ };
const options = { mode: 'shipping' };
const elements = stripe.elements({ 
clientSecret
 });
const linkAuthElement = elements.create('linkAuthentication');
const addressElement = elements.create('address', options);
const paymentElement = elements.create('payment');
linkAuthElement.mount('#link-auth-element');
addressElement.mount('#address-element');
paymentElement.mount('#payment-element');

Appearance

You can use the Appearance API to control the style of all elements. Choose a theme or update specific details.

For instance, choose the “flat” theme and override the primary text color.

const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

const appearance = {
  theme: 'flat',
  variables: { colorPrimaryText: '#262626' }
};

See the Appearance API documentation for a full list of themes and variables.