Listen for address input

First, create a Stripe account or sign in.

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

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

You’re ready to collect address details on the client with the Address Element.

npm install --save @stripe/react-stripe-js @stripe/stripe-js

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(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

function App() {
  const options = {
    // Fully customizable with appearance API.
    appearance: {/*...*/},
  };

  return (
    <Elements stripe={stripe} options={options}>
      <AddressForm />
    </Elements>
  );
};

ReactDOM.render(<App />, document.getElementById('root'));

import React from 'react';
import {AddressElement} from '@stripe/react-stripe-js';

const AddressForm = () => {
  return (
    <form>
      <h3>Shipping</h3>
      <AddressElement options={{mode: 'shipping'}} />
    </form>
  );
};

export default AddressForm;

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 onChange={(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.

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.

<AddressElement options={{
  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:

<AddressElement options={{
  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
<AddressElement options={{
  mode: 'shipping',
  allowedCountries: ['US'],
  blockPoBox: true,
  fields: {
    phone: 'always',
  },
  validation: {
    phone: {
      required: 'never',
    },
  },
}} />

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.