Address Autofill
Mapbox Search JS is in public beta. During the public beta phase, frameworks may be subject to potential changes as they stabilize.
Walk through installing Mapbox Search JS, setting appropriate autocomplete tags, and adding autofill to your application.
Use HTML Custom Elements to add autofill suggestions with Address Autofill in this interactive demo.
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
(AddressAutofillCollectionOptions)AddressAutofillCollectionOptions
Object defining options for Address Autofill search behavior and UI.
Returns
AddressAutofillCollectionTypeExample
<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());
AddressAutofillCollection
Underlying collection object class returned by the autofill function.
Instance Members
Methods
Events
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.
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
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
(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();
});
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
}
});
AddressConfirmShowResult
({type:"change", feature: AddressAutofillFeatureSuggestion} | {type: "nochange"} | {type: "cancel"})getFormAutofillValues
Gets the current input values for address fields given a form and a reference input.
Parameters
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"
// }
getAutofillSearchText
Converts an AutofillValueMap to a single line, suitable for display in a text field.
Parameters
(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'
AutofillValueMap
Object mapping WHATWG autocomplete attribute values to corresponding address component strings.
anyExample
{
"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;
}