> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overflow.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Address elements

> Collect billing and shipping addresses, with optional autocomplete.

Address elements collect a shopper's structured postal address. Use `billingAddress` and `shippingAddress` standalone, or configure them as sections inside [Checkout](/payment-elements/elements/checkout/sections/billing-address).

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

```javascript theme={null}
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](/payment-elements/elements/address/autocomplete)

## Country restriction

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

```javascript theme={null}
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.

```javascript theme={null}
overflow.billingAddress({
  fields: {
    line2: { hidden: true },
  },
});
```

## Submitted value

```javascript theme={null}
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:

```javascript theme={null}
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

<CardGroup cols={2}>
  <Card title="Billing address" href="/payment-elements/elements/address/billing-address">
    Billing-specific configuration.
  </Card>

  <Card title="Shipping address" href="/payment-elements/elements/address/shipping-address">
    Shipping-specific configuration.
  </Card>

  <Card title="Autocomplete" href="/payment-elements/elements/address/autocomplete">
    Google Places autocomplete configuration.
  </Card>

  <Card title="Reference" href="/payment-elements/elements/address/reference">
    Full options and value reference.
  </Card>
</CardGroup>