Listen for address input
Collect addresses to use in custom ways using an event listener.
The Address Element enables you to collect local and international shipping or billing addresses from your customers.
Set up StripeServer-side
First, create a Stripe account or sign in.
Use our official libraries to access the Stripe API from your application:
Collect address detailsClient-side
You’re ready to collect address details on the client with the Address Element.
Set up Stripe.js
The Address Element is automatically available as a feature of Stripe.js. Include the Stripe.js script on your checkout page by adding it to the head
of your HTML file. Always load Stripe.js directly from js.stripe.com to remain PCI compliant. Don’t include the script in a bundle or host a copy of it yourself.
<head> <title>Checkout</title> <script src="https://js.stripe.com/v3/"></script> </head>
Create a Stripe instance
Create an instance of Stripe on your checkout page:
// Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys const stripe = Stripe(
);'pk_test_TYooMQauvdEDq54NiTphI7jx'
Add the Address Element to your page
The Address Element needs a place on your page. Create an empty DOM node (container) with a unique ID in your form.
<form id="address-form"> <h3>Address</h3> <div id="address-element"> <!-- Elements will create form elements here --> </div> </form>
After this form loads, create an instance of the Address Element, specify the address mode and mount it to the container DOM node.
If you already have an Elements instance created, you can use the same instance to create the Address Element. Otherwise, create a new Elements instance first.
const options = { // Fully customizable with appearance API. appearance: { /* ... */ } }; // Only need to create this if no elements group exist yet. // Create a new Elements instance if needed, passing the // optional appearance object. const elements = stripe.elements(options); // Create and mount the Address Element in shipping mode const addressElement = elements.create("address", { mode: "shipping", }); addressElement.mount("#address-element");
Retrieve address detailsClient-side
You can retrieve the address details by listening to the change event. The change
event fires whenever the user updates any field in the Element.
addressElement.on('change', (event) => { if (event.complete){ // Extract potentially complete address const address = event.value.address; } })
Alternatively, you can use getValue.
const handleNextStep = async () => { const addressElement = elements.getElement('address'); const {complete, value} = await addressElement.getValue(); if (complete) { // Allow user to proceed to the next step // Optionally, use value to store the address details } };
In a single-page checkout flow with the Payment Element, the Address Element automatically passes the shipping or billing information when you confirm the PaymentIntent
or SetupIntent
.
In a multi-page checkout flow, you can manually update the PaymentIntent or update the Customer object with the address details received from the change
event or getValue
method before moving to the next step.
Configure the Address ElementClient-side
You can configure the Address Element to suit your needs.
Autocomplete
The Address Element has a built in address autocomplete feature that uses the Google Maps API Places Library. By default, the autocomplete is enabled with a Stripe provided Google Maps API key if any of the following conditions are met:
- In a single page checkout flow where the Payment Element is mounted in the same elements group as the Address Element.
- In a checkout flow that uses the Address Element in an active Link session.
To enable autocomplete in the Address Element for all other scenarios, you can use the autocomplete option with mode
set to google_
. Set the apiKey
to be your own Google Maps API key that’s configured to allow the Places API usage. Your Google Maps API key is only used when the Stripe provided Google Maps API key isn’t available.
Note
If you’ve deployed a CSP and want to enable autocomplete with your own Google Maps API key, include https://maps.
as a connect-src
and script-src
directive. Refer to the Google Maps API official guide for the most updated CSP requirement.
const addressElement = elements.create("address", { mode: "shipping", autocomplete: { mode: "google_maps_api", apiKey: "{YOUR_GOOGLE_MAPS_API_KEY}", }, });
Prefill address form
The Address Element accepts a defaultValues which lets you prefill the address form when the page loads. An Address Element with all values prefilled looks similar to:
const addressElement = elements.create("address", { mode: "shipping", defaultValues: { name: 'Jane Doe', address: { line1: '354 Oyster Point Blvd', line2: '', city: 'South San Francisco', state: 'CA', postal_code: '94080', country: 'US', }, }, });
Other options
Refer to Stripe.js for the complete list of options in detail.
// Sample of a options object const addressElement = elements.create("address", { mode: 'shipping', allowedCountries: ['US'], blockPoBox: true, fields: { phone: 'always', }, validation: { phone: { required: 'never', }, }, });
Validate address detailsClient-side
Stripe provides a few ways to validate for completeness of an address and trigger errors such as “This field is incomplete.” to display on any incomplete individual address fields.
If you’re using the Address Element with a Payment Intent or Setup Intent, use stripe.confirmPayment or stripe.confirmSetup respectively to complete the intent and then validation errors will appear in the Address Element if there are any.
For other use cases such as multi-page checkout flow, use getValue to trigger validation errors to display in the Address Element.