All docschevron-rightMapbox Search JSchevron-rightarrow-leftWeb Referencechevron-rightAddress Autofill

Address Autofill

lightning
Public beta for Mapbox Search JS

Mapbox Search JS is in public beta. During the public beta phase, frameworks may be subject to potential changes as they stabilize.

tutorial
Add Address Autofill to your website
Walk through installing Mapbox Search JS, setting appropriate autocomplete tags, and adding autofill to your application.
chevron-right
example
Autofill suggestions (custom elements)
Use HTML Custom Elements to add autofill suggestions with Address Autofill in this interactive demo.
chevron-right

Address Autofill provides address search and autocomplete functionality for address forms on the web and mobile apps.

Users can search for an address from a single search bar, then select an address from a list of validated results that dynamically responds to user input. When a validated address is selected, individual address form fields automatically populate with the correct address components (e.g., street number, name, suffix, city, state/region, and zip/postcode). Address Autofill also provides a visual map so that users can confirm the address’s accuracy and adjust the map pin as necessary.

With Address Autofill, enrich the customer experience filling out HTML address forms with minimal code:

<form>
<input name="address" autocomplete="shipping address-line1">
<input name="apartment" autocomplete="shipping address-line2">
<input name="city" autocomplete="shipping address-level2">
<input name="state" autocomplete="shipping address-level1">
<input name="country" autocomplete="shipping country">
</form>
<script>
mapboxsearch.autofill({
accessToken: '<access-token>'
})
</script>

autofill

Entry point for Mapbox Address Autofill, for use on standard HTML input elements.

Compared to MapboxAddressAutofill, this function automatically attaches to eligible <input> elements in-place.

You must have a Mapbox access token.

Eligible inputs must be a descendant of a <form> element, and the form must have inputs with proper HTML autocomplete attributes. The input itself must be of autocomplete "street-address" or "address-line1"".

If your application works with browser autofill, you may already have this functionality.

Parameters

optionsArg(AddressAutofillCollectionOptions)AddressAutofillCollectionOptions Object defining options for Address Autofill search behavior and UI.

Returns

AddressAutofillCollectionType

Example

<input type="text" autocomplete="street-address" />
<script>
mapboxsearch.autofill({
accessToken: 'pk.my.token',
options: { country: 'us' }
};
</script>
const collection = autofill({
accessToken: 'pk.my.token',
options
})
myClientSideRouter.on('route', () => collection.update());
Was this section on autofill helpful?

AddressAutofillCollection

Underlying collection object class returned by the autofill function.

new AddressAutofillCollection()

Instance Members

Methods

Events

Was this section on AddressAutofillCollection helpful?

AddressAutofillCollectionOptions

Instance Members

Was this section on AddressAutofillCollectionOptions helpful?

MapboxAddressAutofill

MapboxAddressAutofill, also available as the element <mapbox-address-autofill>, is an element that wraps an address <input> element with intelligent, location-aware autocomplete functionality.

To use this element, you must have a Mapbox access token.

This element must be a descendant of a <form> element, and the form must have inputs with proper HTML autocomplete attributes. If your application works with browser autofill, you may already have this functionality.

new MapboxAddressAutofill()

Example

<form>
<mapbox-address-autofill access-token="<your access token here>">
<input type="text" name="address" autocomplete="shipping street-address" />
</mapbox-address-autofill>
</form>

Instance Members

Methods

Events

Was this section on MapboxAddressAutofill helpful?

confirmAddress

A utility that can be run prior to form submission that allows a user to correct or confirm an address.

This parses and compares an address entered into form fields with the closest address suggestion from the Mapbox Address Autofill API. Unless an exact match or a custom comparison callback evaluates to true, the user will be shown a modal dialog asking if they would like to use the suggested address.

When a suggested address is accepted, the values are automatically updated in the form fields.

Parameters

form(HTMLFormElement)HTML form that includes the autocomplete-compliant input fields
optionsArg(AddressConfirmOptions)(default {})AddressConfirmOptions Object defining options for Address Autofill API, UI, form parsing, and address comparison

Returns

Promise<AddressConfirmShowResult>: A promise resolving with a result object indicating the decision made by the user

Example

form.addEventListener("submit", async (e) => {
e.preventDefault();
const result = await confirmAddress(form, {
minimap: true,
skipConfirmModal: (feature) =>
['exact', 'high'].includes(
feature.properties.match_code.confidence
)
});
if (result.type === 'nochange') submitForm();
});
Was this section on confirmAddress helpful?

AddressConfirmOptions

Instance Members

Was this section on AddressConfirmOptions helpful?

ConfirmationMinimapOptions

Styling and theming options for a MapboxAddressMinimap embedded inside a confirmation dialog.

Partial<Pick<MapboxAddressMinimap, ("defaultMapStyle" | "theme" | "mapStyleMode" | "satelliteToggle")>>

Example

const result = await confirmAddress(form, {
accessToken: 'abc-123',
minimap: {
defaultMapStyle: ['mapbox', 'outdoors-v11'],
theme: { icons: { marker: MARKER_SVG } },
mapStyleMode: 'default',
satelliteToggle: true
}
});
Was this section on ConfirmationMinimapOptions helpful?

AddressConfirmShowResult

({type: "change", feature: AddressAutofillFeatureSuggestion} | {type: "nochange"} | {type: "cancel"})
Was this section on AddressConfirmShowResult helpful?

getFormAutofillValues

Gets the current input values for address fields given a form and a reference input.

Parameters

form(HTMLFormElement)HTML form that includes the autocomplete-compliant input fields
ref(HTMLInputElement)An input element within the desired form address section

Returns

AutofillValueMap: A object mapping WHATWG autocomplete properties to their respective form field values

Example

const form = document.querySelector(form);
const input = form.querySelector('input[autocomplete~="street-address"]')
const valueMap = getFormAutofillValues(form, input);
console.log(valueMap);
// {
// "street-address": "123 Main",
// "address-level2": "Boston",
// "address-level1": "MA",
// "postal-code": "02129"
// }
Was this section on getFormAutofillValues helpful?

getAutofillSearchText

Converts an AutofillValueMap to a single line, suitable for display in a text field.

Parameters

snapshot(AutofillValueMap)An object mapping WHATWG autocomplete attribute values to their corresponding input field values

Returns

string: A concatenated address string

Example

const values = {
'street-address': '123 Main St',
'address-level1': 'CA',
'address-level2': 'San Francisco',
'address-level3': '',
};
const searchText = getAutofillSearchText(values);
console.log(searchText); // '123 Main St, San Francisco, CA'
Was this section on getAutofillSearchText helpful?

AutofillValueMap

Object mapping WHATWG autocomplete attribute values to corresponding address component strings.

any

Example

{
"street-address"?: string;
"address-line1"?: string;
"address-line2"?: string;
"address-line3"?: string;
"address-level4"?: string;
"address-level3"?: string;
"address-level2"?: string;
"address-level1"?: string;
country?: string;
"country-name"?: string;
"postal-code"?: string;
}
Was this section on AutofillValueMap helpful?