Address Autofill | Mapbox Search JS

Address Autofill provides a rich UI for address search and autocomplete functionality for address forms in websites and web apps.

This page includes reference documentation for elements, functions, and types related to Address Autofill and Address Confirmation features of the Mapbox Search JS Web framework.

For installation instructions and a helpful introduction to using Address Autofill in your website or app, see our Web Address Autofill Quickstart Guide.

Automatic Attachment to Form

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

Search Instance Members

Methods

Events

Was this section on AddressAutofillCollection helpful?

HTML Custom Element

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_MAPBOX_ACCESS_TOKEN">
    <input type="text" name="address" autocomplete="shipping street-address" />
  </mapbox-address-autofill>
</form>

Instance Members

Search Instance Members

Methods

Events

Was this section on MapboxAddressAutofill helpful?

Functions

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?

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?

Options and Type Definitions

AddressAutofillCollectionOptions

Type

Object

Properties

accessToken(string): The Mapbox access token to use for all requests.

browserAutofillEnabled(boolean): Enables the browser's autocomplete popup to show during the first two typed characters while Mapbox results are suppressed. Defaults to false.

Note: Due to varying specifications, efforts to suppress browser autocomplete behavior may not work on all browsers.

confirmOnBrowserAutofill((boolean | AddressConfirmOptions)): If true, forms autofilled by the browser will prompt the confirmAddress dialog for user confirmation. An AddressConfirmOptions object can also be passed to prompt confirmAddress with custom options. Defaults to false.

options(Partial<AddressAutofillOptions>): Options to pass to the underlying AddressAutofillCore interface.

popoverOptions(Partial<PopoverOptions>): The PopoverOptions to define popover positioning.

theme(Theme): The Theme to use for styling the autofill component.

Was this section on AddressAutofillCollectionOptions helpful?

AutofillValueMap

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

Type

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?

AddressConfirmOptions

Type

Object

Properties

accessToken(string): Mapbox access token used for the Address Autofill and Static Image APIs

footer((boolean | string)): Custom footer text appearing at the bottom of the confirmation modal dialog. If true or left undefined, the default footer text will be used. If false , the footer will not be shown.

minimap((boolean | ConfirmationMinimapOptions)): If true, a static minimap showing the suggested address location will be displayed in the modal dialog. If an object, a minimap will be displayed with the specified styling and theming configuration. Defaults to false.

options(Partial<ValidationOptions>): Address Autofill API configuration options ValidationOptions

sections(Array<string>): An array of section names used within form element autocomplete attributes to identify and group one address section from another, e.g. "section-shipping" or "section-billing". These are often used when a single contains multiple logical sections. If left undefined, all discoverable sections will be processed.

skipConfirmModal(function (feature: AddressAutofillFeatureSuggestion): boolean): A callback used to pre-confirm an address and skip the UI modal. The feature argument contains all address components, as well as an MatchCode object, which are used to express the confidence of an address match. The callback must return a boolean, with true indicating that the address has been pre-confirmed, and the UI modal will be skipped and will not be presented to the end-user. If left undefined, this defaults to skipping showing the modal when the validated feature's match code returns an "exact" match.

theme(Theme): CSS variables and icons

Was this section on AddressConfirmOptions helpful?


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