# 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 Stripe
Use our official libraries to access the Stripe API from your application:
```bash
\# Available as a gem
sudo gem install stripe
```
```ruby
\# If you use bundler, you can add this line to your Gemfile
gem 'stripe'
```
```bash
\# Install through pip
pip3 install --upgrade stripe
```
```bash
\# Or find the Stripe package on http://pypi.python.org/pypi/stripe/
```
```python
\# Find the version you want to pin:
# https://github.com/stripe/stripe-python/blob/master/CHANGELOG.md
# Specify that version in your requirements.txt file
stripe>=5.0.0
```
```bash
\# Install the PHP library with Composer
composer require stripe/stripe-php
```
```bash
\# Or download the source directly: https://github.com/stripe/stripe-php/releases
```
```java
/*
For Gradle, add the following dependency to your build.gradle and replace with
the version number you want to use from:
- https://mvnrepository.com/artifact/com.stripe/stripe-java or
- https://github.com/stripe/stripe-java/releases/latest
*/
implementation "com.stripe:stripe-java:29.0.0"
```
```xml
com.stripe
stripe-java
29.0.0
```
```bash
\# For other environments, manually install the following JARs:
# - The Stripe JAR from https://github.com/stripe/stripe-java/releases/latest
# - Google Gson from https://github.com/google/gson
```
```bash
\# Install with npm
npm install stripe --save
```
```bash
\# Make sure your project is using Go Modules
go mod init
# Install stripe-go
go get -u github.com/stripe/stripe-go/v82
```
```go
// Then import the package
import (
"github.com/stripe/stripe-go/v82"
)
```
```bash
\# Install with dotnet
dotnet add package Stripe.net
dotnet restore
```
```bash
\# Or install with NuGet
Install-Package Stripe.net
```
## Collect address details
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.
```html
Checkout
```
### Create a Stripe instance
Create an instance of Stripe on your checkout page:
```javascript
// 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('<>');
```
### 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.
```html
```
After this form loads, create an instance of the Address Element, specify the address [mode](https://docs.stripe.com/js/elements_object/create_address_element#address_element_create-options-mode) and mount it to the container DOM node.
If you already have an [Elements](https://docs.stripe.com/js/elements_object/create) instance created, you can use the same instance to create the Address Element. Otherwise, create a new [Elements](https://docs.stripe.com/js/elements_object/create) instance first.
```javascript
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");
```
```javascript
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 billing mode
const addressElement = elements.create("address", {
mode: "billing",
});
addressElement.mount("#address-element");
```
### Set up Stripe.js
Install [React Stripe.js](https://www.npmjs.com/package/@stripe/react-stripe-js) and the [Stripe.js loader](https://www.npmjs.com/package/@stripe/stripe-js) from the npm public registry.
```bash
npm install --save @stripe/react-stripe-js @stripe/stripe-js
```
### Add and configure the Elements provider to your page
To use the Address Element component, wrap your checkout page component in an [Elements provider](https://docs.stripe.com/sdks/stripejs-react.md#elements-provider). Call `loadStripe` with your publishable key. Pass the returned `Promise` to the `Elements` provider.
```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import {Elements} from '@stripe/react-stripe-js';
import {loadStripe} from '@stripe/stripe-js';
import AddressForm from './AddressForm';
// Make sure to call `loadStripe` outside of a component’s render to avoid
// recreating the `Stripe` object on every render.
const stripe = loadStripe('<>');
function App() {
const options = {
// Fully customizable with appearance API.
appearance: {/*...*/},
};
return (
);
};
ReactDOM.render(, document.getElementById('root'));
```
### Add the Address Element component
Use the `AddressElement` component to build your form.
```jsx
import React from 'react';
import {AddressElement} from '@stripe/react-stripe-js';
const AddressForm = () => {
return (
);
};
export default AddressForm;
```
```jsx
import React from 'react';
import {AddressElement} from '@stripe/react-stripe-js';
const AddressForm = () => {
return (
);
};
export default AddressForm;
```
## Retrieve address details
You can retrieve the address details by listening to the [change](https://docs.stripe.com/js/element/events/on_change?type=addressElement) event. The `change` event fires whenever the user updates any field in the Element.
```javascript
addressElement.on('change', (event) => {
if (event.complete){
// Extract potentially complete address
const address = event.value.address;
}
})
```
```jsx
{
if (event.complete) {
// Extract potentially complete address
const address = event.value.address;
}
}} />
```
Alternatively, you can use [getValue](https://docs.stripe.com/js/elements_object/get_value_address_element).
```javascript
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](https://docs.stripe.com/payments/payment-element.md), 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](https://docs.stripe.com/api/payment_intents/update.md) or [update the Customer object](https://docs.stripe.com/api/customers/update.md) with the address details received from the `change` event or `getValue` method before moving to the next step.
## Configure the Address Element
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](https://developers.google.com/maps/documentation/javascript/places). 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](https://docs.stripe.com/payments/payment-element.md) is mounted in the same elements group as the Address Element.
- In a checkout flow that uses the Address Element in an active [Link](https://docs.stripe.com/payments/link.md) session.
To enable autocomplete in the Address Element for all other scenarios, you can use the [autocomplete](https://docs.stripe.com/js/elements_object/create_address_element#address_element_create-options-autocomplete) option with `mode` set to `google_maps_api`. Set the `apiKey` to be your own [Google Maps API key](https://developers.google.com/maps/documentation/javascript/get-api-key#create-api-keys) that’s configured to allow the [Places API](https://developers.google.com/maps/documentation/javascript/places#add-places-api-to-the-api-keys-api-restrictions-list) usage. Your Google Maps API key is only used when the Stripe provided Google Maps API key isn’t available.
If you’ve deployed a [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/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](https://developers.google.com/maps/documentation/javascript/content-security-policy) for the most updated CSP requirement.
```javascript
const addressElement = elements.create("address", {
mode: "shipping",
autocomplete: {
mode: "google_maps_api",
apiKey: "{YOUR_GOOGLE_MAPS_API_KEY}",
},
});
```
```jsx
```
### Prefill address form
The Address Element accepts a [defaultValues](https://docs.stripe.com/js/elements_object/create_address_element#address_element_create-options-defaultValues) which lets you prefill the address form when the page loads. An Address Element with all values prefilled looks similar to:
```javascript
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',
},
},
});
```
```jsx
```
### Other options
Refer to [Stripe.js](https://docs.stripe.com/js/elements_object/create_address_element#address_element_create-options) for the complete list of options in detail.
```javascript
// Sample of a options object
const addressElement = elements.create("address", {
mode: 'shipping',
allowedCountries: ['US'],
blockPoBox: true,
fields: {
phone: 'always',
},
validation: {
phone: {
required: 'never',
},
},
});
```
```jsx
// Sample of a options object
```
## Validate address details
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](https://docs.stripe.com/js/payment_intents/confirm_payment) or [stripe.confirmSetup](https://docs.stripe.com/js/setup_intents/confirm_setup) 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](https://docs.stripe.com/js/elements_object/get_value_address_element) to trigger validation errors to display in the Address Element.
## Customize the appearance
Now that you’ve added the Address Element to your page, you can customize the appearance to fit with the design of the rest of your page. See the [Appearance API](https://docs.stripe.com/elements/appearance-api.md) page for more information.
