Address autocomplete

Address elements support optional address autocomplete via a top-level addressAutocomplete option. Opt in by presence; omit the option to disable.

Providers

The only provider supported today is Google Maps Places API (New). Bring your own API key — Overflow does not relay it.

overflow.billingAddress({
  addressAutocomplete: {
    provider: 'googlePlaces',
    apiKey: 'AIza...',
  },
});

Options

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:

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. Below it, an “Enter address manually” link expands the full form. Picking a suggestion, clicking the manual link, or calling submit() with unpicked text also expands the form.
'manual': the full form renders immediately, with the search input attached to line1.

Country restriction

When fields.country.supportedCountries is set on the address element, that country list is forwarded to Google Places and suggestions are limited to those countries.

Suggestion pick behavior

When a shopper picks a suggestion, all address atoms are filled from the place: line1, city, state, zip, country, and line2 if the place has a subpremise (apartment/suite). A single onChange fires with the populated value. If the shopper then edits any atom, the address is treated as user-edited.

Same API key for billing and shipping

If autocomplete is configured on both billing and shipping, pass the same apiKey on both — the first mount’s key wins for the lifetime of the page.

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;

Graceful failure

If Google Maps fails to load (network error, invalid key, blocked by CSP), the address inputs continue to work as plain fields — the shopper can still type and submit an address. A single warning is logged; onError does not fire.

Get started

Elements

Options

Events

Theming

Guides

Providers

Options

`includedPrimaryTypes`

`inputMode`

Country restriction

Suggestion pick behavior

Same API key for billing and shipping

Content Security Policy

Graceful failure

See also

​Providers

​Options

​includedPrimaryTypes

​inputMode

​Country restriction

​Suggestion pick behavior

​Same API key for billing and shipping

​Content Security Policy

​Graceful failure

​See also

Providers

Options

`includedPrimaryTypes`

`inputMode`

Country restriction

Suggestion pick behavior

Same API key for billing and shipping

Content Security Policy

Graceful failure

See also