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.
In shipping mode, the element does two things:
- Collect a shipping address.
- Offer the customer the option to use it as a billing address too.
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);
const appearance = { };
const options = { mode: 'shipping' };
const elements = stripe.elements({ , appearance });
const addressElement = elements.create('address', options);
addressElement.mount('#address-element');
Use Address Element with other elements
You can collect both shipping and billing addresses by using multiple Address Elements, one of each mode, on your page.
If you need to collect both shipping and billing addresses and only want to use one Address Element, use the Address Element in Shipping mode and use the Payment Element to collect only the necessary billing address details.
When you use the Address Element with other elements, you can expect some automatic behavior when confirming the PaymentIntent or SetupIntent. The Address Element validates completeness upon confirming the PaymentIntent or SetupIntent and then displays errors for each field if there are any validation errors.
Use an address
The Address Element automatically works with the Payment or Express Checkout 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.
In shipping mode, the address is stored in these fields:
- It appears in the shipping field.
- If the customer indicates it is also the billing address, it also appears in the billing_details field.
To enable combining information, create all elements from the same Elements
object, as in this example:
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);
const appearance = { };
const options = { mode: 'shipping' };
const elements = stripe.elements({ });
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 might 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 saves and autofills payment and shipping information. When a returning Link customer authenticates, Stripe autofills their shipping information in the Address element.
Create a payment form using multiple Elements
To enable autofill, create all elements from the same Elements
object, as in this example:
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);
const appearance = { };
const options = { mode: 'shipping' };
const elements = stripe.elements({ });
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.
See the Appearance API documentation for a full list of themes and variables.