Skip to main content
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):
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

​
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:

​
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:
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 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

Last modified on July 17, 2026