Address elements

Address elements collect a shopper’s structured postal address. Use billingAddress and shippingAddress standalone, or configure them as sections inside Checkout. Both elements share the same field set and options surface. billingAddress is designed to pair with a payment method (card or bank); shippingAddress is designed to pair with an order.

Elements

Element	Factory	Use for
Billing address	`overflow.billingAddress()`	Cardholder or bank account billing address.
Shipping address	`overflow.shippingAddress()`	Order shipping destination.

Fields

Both elements render the same address atoms:

line1 (street address)
line2 (apartment, suite, or unit; optional)
city
state
postalCode
country

Optional slots (opt-in):

fullName (a full-name element rendered above the address atoms)
companyName (a company-name element rendered between fullName and the atoms)

Standalone example

const overflow = new Overflow('live_pub_...');

const billing = overflow.billingAddress({
  fields: {
    fullName: {},
    line2: { hidden: true },
    country: { supportedCountries: ['US', 'CA'] },
  },
});

billing.on('onChange', ({ complete, value }) => {
  console.log('complete:', complete, 'value:', value);
});

billing.mount('#billing');

Autocomplete

Both address elements support optional address autocomplete. Opt in with a top-level addressAutocomplete option. The full configuration, provider details, and CSP guidance live on one page:

Address autocomplete

Country restriction

Restrict the country dropdown (and, when autocomplete is enabled, the suggestion pool) with fields.country.supportedCountries:

overflow.billingAddress({
  fields: {
    country: {
      supportedCountries: ['US', 'CA', 'GB'],
    },
  },
});

Set fields.country.defaultCountry to preselect a country. If unset, the element preselects based on the shopper’s inferred locale.

Hidden fields

Collapse any atom with fields.<atom>.hidden: true. Hidden fields are skipped during validation, so they never block completion.

overflow.billingAddress({
  fields: {
    line2: { hidden: true },
  },
});

Submitted value

billing.on('onSubmit', ({ value }) => {
  // value.line1, value.line2?, value.city, value.state, value.postalCode, value.country
  // value.fullName?    { firstName, lastName } | null when configured, undefined when omitted.
  // value.companyName? '' when configured and empty, string when typed, undefined when omitted.
});

Inside Checkout

Configure billing and shipping the same way inside Checkout:

overflow.checkout({
  paymentMethods: ['card'],
  billingAddress: { fields: { line2: { hidden: true } } },
  shippingAddress: {
    fields: { country: { supportedCountries: ['US', 'CA'] } },
  },
});

When both are configured, Checkout renders a “Same as shipping” toggle on the billing section (default checked).

Next steps

Billing address

Billing-specific configuration.

Shipping address

Shipping-specific configuration.

Autocomplete

Google Places autocomplete configuration.

Reference

Full options and value reference.

Get started

Elements

Options

Events

Theming

Guides

Elements

Fields

Standalone example

Autocomplete

Country restriction

Hidden fields

Submitted value

Inside Checkout

Next steps

Billing address

Shipping address

Autocomplete

Reference

​Elements

​Fields

​Standalone example

​Autocomplete

​Country restriction

​Hidden fields

​Submitted value

​Inside Checkout

​Next steps

Billing address

Shipping address

Autocomplete

Reference

Elements

Fields

Standalone example

Autocomplete

Country restriction

Hidden fields

Submitted value

Inside Checkout

Next steps