Beta
Mapbox Search JS

Address Autofill

Private beta for Mapbox Search JS

Mapbox Search JS is in private beta. During the private 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.

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(AutofillCollectionOptions)
NameDescription
optionsArg.accessToken
string
A Mapbox access token .
optionsArg.options
Partial<AutofillOptions>?
Options to set on the underlying Autofill API.

Returns

AutofillCollectionType

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());

AutofillCollection

Underlying collection object class returned by the autofill function.

new AutofillCollection()

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.

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

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 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 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();
});

AddressConfirmOptions

Instance Members

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: AutofillFeatureSuggestion} | {type: "nochange"} | {type: "cancel"})

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"
// }

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'