Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in

Listen for address input

Collect addresses to use in custom ways using an event listener.

Theme
Size
Customer Location
Phone number
Autocomplete
Contacts

The Address Element enables you to collect local and international shipping or billing addresses from your customers.

Set up Stripe
Server-side

First, create a Stripe account or sign in.

Use our official libraries to access the Stripe API from your application:

Command Line
# Available as a gem
sudo gem install stripe
Gemfile
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Collect address details
Client-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.

checkout.html
<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:

checkout.js
// 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.

checkout.html
<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.

checkout.js
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 details
Client-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.

checkout.js
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 Element
Client-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_maps_api. 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.googleapis.com 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 details
Client-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.

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc
On this page
Set up Stripe
Collect address details
Retrieve address details
Configure the Address Element
Autocomplete
Prefill address form
Other options
Validate address details
Products Used
Elements
Payments