> ## 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 autocomplete

> Optional address autocomplete for billing and shipping elements.

Address elements support optional address autocomplete via a top-level `addressAutocomplete` option. Opt in by presence; omit the option to disable. Autocomplete lives at the element level (not per atom) because picking a suggestion fills every atom in one pass.

## Providers

The only provider supported today is Google Maps Places API (New):

```javascript theme={null}
overflow.billingAddress({
  addressAutocomplete: {
    provider: 'googlePlaces',
    apiKey: 'AIza...',
  },
});
```

Future providers will extend the option type; provider selection stays a discriminated field.

## Bring your own key

Overflow does not relay your Google Maps API key. Every merchant supplies their own via `apiKey`. The key is used directly by the Google Maps JavaScript API and is loaded from `maps.googleapis.com`.

## Options

```typescript theme={null}
type AddressAutocomplete = {
  provider: 'googlePlaces';
  apiKey: string;                                             // required
  includedPrimaryTypes?: ReadonlyArray<
    'street_address' | 'establishment'
  >;                                                          // default: ['street_address']
  inputMode?: 'inline' | 'manual';                            // default: 'inline'
};
```

### `includedPrimaryTypes`

Controls what kinds of results appear in the suggestion list.

* `'street_address'` (default): residential and other precise street addresses. Best for consumer checkout.
* `'establishment'`: businesses, points of interest, and other named locations. Useful for B2B billing or wholesale shipping.

Combine both to accept residential and business suggestions in the same dropdown:

```javascript theme={null}
addressAutocomplete: {
  provider: 'googlePlaces',
  apiKey: 'AIza...',
  includedPrimaryTypes: ['street_address', 'establishment'],
}
```

### `inputMode`

Selects the visible layout.

* `'inline'` (default): the address block collapses to a single search input bound to `line1`. Below the input, an "Enter address manually" link expands the full six-atom form. Optional `fullName` and `companyName` slots continue to render above.
* `'manual'`: the full six-atom form renders immediately, with the search input attached to `line1`.

The mode is read once on mount. Runtime transitions between inline and manual are internal.

**Auto-expand from inline to manual triggers on:**

1. Picking a suggestion. All atoms are filled and the form expands so the shopper can review or tweak.
2. Clicking "Enter address manually". Empty atoms are preserved and the shopper continues from a blank form.
3. Calling `submit()` while the input has typed-but-unpicked text. The form expands synchronously so the atoms mount and run normal validation.

### `componentRestrictions`

When `fields.country.supportedCountries` is set on the same address element, that country list is forwarded to Google Places as the suggestion restriction. Suggestions are limited to those countries.

When `supportedCountries` is unset, no country restriction is applied to the autocomplete query.

## Suggestion pick behavior

When a shopper picks a suggestion:

* All six address atoms are replaced with the picked place's components: `line1`, `city`, `state`, `postalCode`, `country`.
* `line2` is populated when the place has a subpremise component, otherwise cleared. Shoppers fill in apartment or suite themselves.
* A single `onChange` fires after the pick with the populated value.

If the shopper subsequently edits any atom, the address is treated as user-edited and the picked place ID is cleared.

## Single-key constraint (Google-specific)

Google's bootstrap loader can only be initialized once per page with a single API key. This drives a runtime constraint:

* The first `provider: 'googlePlaces'` mount on the page wins. Its `apiKey` becomes the active key for the lifetime of the page.
* Later mounts with a **different** `apiKey` value log a warning and reuse the first key.
* Later mounts with the **same** `apiKey` are no-ops (the loader promise is already resolved).

Merchants who configure autocomplete on both billing and shipping must pass the same `apiKey` literal on both.

## Loading and bundle isolation

* The Google Maps JavaScript API is fetched lazily from `maps.googleapis.com` the first time a `provider: 'googlePlaces'` mount runs. Merchants who never opt in never trigger that fetch.
* The Google Maps SDK is roughly 50-100 KB gzipped.
* The bootstrap script auto-detects an existing `<script nonce="...">` tag on the page and reuses the nonce, so CSP-protected sites only need to configure their nonce on a single tag.

## Content Security Policy

If your site sets a Content Security Policy, allow the Google Maps host:

```
script-src 'self' https://maps.googleapis.com https://cdn.overflow.co;
connect-src 'self' https://maps.googleapis.com https://cdn.overflow.co https://server.overflow.co;
```

The bootstrap injects a `<script>` tag pointed at `maps.googleapis.com`; it must be allowed to load and connect.

## Graceful failure

If the Google Maps JavaScript API fails to load (network error, invalid key, blocked by CSP, etc.):

* A single warning is logged to the browser console.
* The address atoms continue to work as plain inputs. The shopper can still type and submit a valid address manually.
* The element's `onError` channel does not fire. Autocomplete is an enhancement, not a contract.

## Theming

The autocomplete widget inherits your theme through the address element's design tokens: `colorPrimary`, `colorBorder`, `colorText`, `borderRadius`, and typography tokens apply to both the search input and the suggestion list.

Fine-grained internals (the focus ring, prediction rows, matched substring emphasis, and the row icon) are also themed by tokens rather than direct CSS. Refer to [Theming](/payment-elements/theming/overview) for the full token list.

The `::part(input)` selector on the underlying widget is an implementation detail and is not part of the theming surface.

## Out of scope

* Other autocomplete providers (Mapbox, Azure, etc.). The provider discriminator is reserved for future additions.
* A "verified by Places" flag on submitted values.
* A callback for autocomplete load failures beyond the console warning.

## See also

* [Billing address](/payment-elements/elements/address/billing-address)
* [Shipping address](/payment-elements/elements/address/shipping-address)
* [Installation](/payment-elements/installation) for CSP baseline entries