Address Autocomplete
Address autocomplete suggests addresses as the visitor types into the street-address field and fills the rest of the address (city, state, postal, country) on selection. It attaches automatically to the checkout form's address fields — there is no separate attribute to add.
Providers
Two providers are supported. The SDK picks one based on your configuration, preferring Google Maps when both are configured.
| Provider | Enabled by | Notes |
|---|---|---|
| Google Maps | Google Maps config with an API key and autocomplete enabled | Uses Google Places; loads the Maps script on first focus |
| NextCommerce | Address config with autocomplete enabled | Uses the NextCommerce address API; no third-party script |
Autocomplete is lazy-loaded — the provider script/API is only initialized the first time the visitor focuses the address1 (or billing-address1) field, so it adds nothing to initial page load.
Fields It Fills
Selecting a suggestion fills the standard address fields. It works for both shipping and billing:
- Shipping:
address1,city,province,postal,country - Billing:
billing-address1,billing-city,billing-province,billing-postal,billing-country
Each filled field fires a native change event so validation and dependent UI (like the revealed location block) update normally.
Behavior
- Google Maps — suggestions come from Google Places; the SDK parses the chosen place into the address fields, handling country-specific formats.
- NextCommerce — input is debounced (~300ms) before querying; suggestions support keyboard navigation (Up/Down to move, Enter to select, Escape to close).
When an address is filled, the SDK emits address:autocomplete-filled with { type: 'shipping' | 'billing' } and tracks an add_shipping_info analytics event.
Requirements
- For Google Maps, a valid Maps JavaScript API key with the Places library, set in your SDK config.
- For NextCommerce, autocomplete enabled in your address config.
If neither is configured, the address fields behave as plain inputs.
Next Steps
- The fields autocomplete fills: The Form
- SDK configuration: Configuration
- The
address:autocomplete-filledpayload: Reference → Events