メインコンテンツまでスキップ

Address Autofill - Web Quickstart

Address Autofill is a Mapbox Search JS feature that makes filling out postal addresses on web forms faster, easier, and more accurate. It presents the user with suggested address matches after they begin typing in your form. Users can click a suggested address and instantly fill in the remaining inputs (city, state, postal code, etc).

Address autofill allows users to enter their information with fewer keystrokes and provide more accurate information.

This Quickstart Guide will help you get started with Address Autofill using Mapbox Search JS Web.

To use Address Autofill in a React app, see the Address Autofill React Quickstart.

Prerequisites​

To use Mapbox Search JS, you need to have a Mapbox access token.

Your default public token​

You can use your default public token to get started with the code snippets in this guide.

To get your default public token, login to account.mapbox.com and scroll down to the Access Tokens section.

This access token associates your search requests with a Mapbox account for billing. For more information on creating and using access tokens, see our token management documentation.

Installation​

There are two ways to include Mapbox Search JS depending on your web project's architecture. You can use the Mapbox CDN to quickly add Mapbox Search JS to any web page with a <script> tag. For more complex projects that use a javascript module bundler such as webpack or rollup, you can install Mapbox Search JS via npm.

Installation when using the Mapbox CDN​

Include the Mapbox Search JS Web framework in your project by adding the following <script> tag to the <head> in your HTML file.

<script id="search-js" defer src="https://api.mapbox.com/search-js/v1.5.0/web.js"></script>

This script will give you access to Mapbox Search JS Web classes (MapboxAddressAutofill,MapboxSearchBox MapboxGeocoder, etc ) as well as the mapboxsearch global object.

Installation when using a Module Bundler​

Install the NPM package.

npm install --save @mapbox/search-js-web

There is no default export for @mapbox/search-js-web, you must use named exports.

import { MapboxAddressAutofill, MapboxSearchBox, MapboxGeocoder, config } from '@mapbox/search-js-web'

Using Address Autofill​

There are three ways to add Address Autofill to your forms:

  • The autofill() function (recommended for most pages) — discovers eligible inputs across your page and attaches autofill automatically. One line of setup; works with any form that has proper HTML autocomplete attributes.
  • The <mapbox-address-autofill> HTML custom element — declarative; wrap your <input> elements in HTML markup with no JavaScript required. Useful when you want explicit, individual form control without writing JS.
  • The MapboxAddressAutofill class — for fine-grained imperative control. Use when you need to attach autofill to specific inputs from JavaScript, configure multiple inputs with different options, or work with inputs that don't follow the discovery convention.

Automatic attachment with autofill()​

The autofill() function automatically attaches to eligible <input> elements and is the easiest and fastest way to add address autofill to your website.

Eligible inputs must be a descendant of a <form> element, and the form must have inputs with appropriate HTML autocomplete attributes.

<form>
  <input type="text" name="address-1" autocomplete="address-line1" />
  <input type="text" name="address-2" autocomplete="address-line2" />
  <input type="text" name="city" autocomplete="address-level2" />
  <input type="text" name="state" autocomplete="address-level1" />
  <input type="text" name="zip" autocomplete="postal-code" />
</form>
import { autofill, config } from '@mapbox/search-js-web'

config.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN'

autofill({
  options: {
    country: 'us'
  }
})
EXAMPLE
Autofill suggestions example

This example uses the autofill() function to automatically add suggestions to an address input.

Declarative attachment with <mapbox-address-autofill>​

The <mapbox-address-autofill> HTML custom element wraps your <input> elements directly in markup, with configuration set via HTML attributes — no JavaScript setup required. This is the simplest path when you want explicit, individual form control and your page is server-rendered or otherwise written as HTML.

<mapbox-address-autofill> must be a descendant of a <form> element and must wrap the <input> element with the address-line1 autocomplete attribute.

HTML attributes differ from JS class properties

HTML attribute names are kebab-case versions of the JS class properties — access-token instead of accessToken, popover-options instead of popoverOptions. Because HTML attributes only hold strings, the API options that you'd pass as a single options object on the class (language, country, bbox, limit, proximity, streets) become individual top-level attributes here, and object-valued options like theme and popover-options accept JSON-encoded strings.

<form>
    <mapbox-address-autofill
      access-token="YOUR_MAPBOX_ACCESS_TOKEN"
      theme='{"variables": {"colorText": "#32a852"}}'
      popover-options='{"offset": 30}'
    >
      <input
        type="text"
        name="address-1"
        autocomplete="address-line1"
        placeholder="Address"
      />
    </mapbox-address-autofill>
      <input
        type="text"
        name="address-2"
        autocomplete="address-line2"
        placeholder="Apartment, suite, etc. (optional)"
      />
      <div class="city-state-zip">
          <input
            type="text"
            name="address"
            autocomplete="address-level2"
            placeholder="City"
          />
          <input
            type="text"
            name="address"
            autocomplete="address-level1"
            placeholder="State"
          />
          <input
            type="text"
            name="address"
            autocomplete="postal-code"
            placeholder="ZIP Code"
          />
      </div>
</form>

In the above example, the custom element has its access-token, theme, and popover-options attributes set.

EXAMPLE
Autofill suggestions (custom elements) example

Try the full Address Autofill workflow on a working address form using the HTML custom element.

Using the MapboxAddressAutofill class​

MapboxAddressAutofill is a JavaScript class. Instantiating it produces a DOM element that you place inside a <form> to wrap one or more <input> elements with location-aware autocomplete.

To use MapboxAddressAutofill instantiate the class, add your access token (required), configure it with the available parameters (optional), wrap your <input>, and append it to a <form>. The same placement rules apply: the autofill element must be a descendant of a <form> and must contain <input> elements with appropriate autocomplete attributes.

<form>
  <input id="address-input" type="text" name="address" autocomplete="shipping street-address" />
</form>
import { MapboxAddressAutofill } from '@mapbox/search-js-web'

// instantiate a new MapboxAddressAutofill
const autofillElement = new MapboxAddressAutofill()

autofillElement.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN'

// set the autofill options
autofillElement.options = {
  country: 'us'
}

const addressInput = document.getElementById('address-input');
const addressForm = addressInput.parentElement;

// wrap the <input> with the MapboxAddressAutofill instance
autofillElement.appendChild(addressInput);
// append the MapboxAddressAutofill instance to the <form>
addressForm.appendChild(autofillElement);

Address Confirmation​

Address confirmation lets users match their address against our comprehensive database and presents a confirmation dialog. This workflow is usually triggered during form submission, providing a higher quality address to match the user's input if one can be found.

With the minimap option, a small map image is presented with a pin for visual confirmation of an address. The user can move the pin to provide details about the physical delivery location that matches the address.

To implement Address Confirmation, intercept the form submission and call the asynchronous function confirmAddress(), passing in the form element. confirmAddress() returns an object with the type property set to either 'change', 'nochange', or 'cancel' based on the user's actions. You can then continue with form submission using the original address or the suggested address.

'change' indicates that the Autofill API found a better match and the user selected it for use. In this case, a feature property is also included in the returned object which includes the suggested match. 'nochange' indicates that the user chose to use the address they provided instead of the suggested address. 'cancel' indicates that the user closed the confirmation dialog.

import { confirmAddress } from '@mapbox/search-js-web'

const form = document.querySelector("form");

form.addEventListener("submit", async (e) => {
  // do not submit the form
  e.preventDefault();
  const result = await confirmAddress(form, {
    minimap: true
  });

  // submit the original address if the user did not select a better match
  if (result.type === 'nochange') submitForm();
  // submit the address data from the better match chosen by the user
  if (result.type === 'change') {
    submitFormWithChanges(result.feature)
  };
});

The Minimap can also be implemented on its own via the MapboxAddressMinimap class.

EXAMPLE
Address Confirmation example

Try out the Mapbox Search JS Address Confirmation workflow with a working address form.

Autocomplete Attributes​

Address Autofill requires HTML autocomplete tags, a standard browser feature. Google Chrome, Mozilla Firefox, and Safari use autocomplete to autofill addresses and credit cards. You may already have autocomplete tags.

You can test this on your website with using the JavaScript Console. After opening the Console, run the following command:

document.querySelector('[autocomplete~="street-address"], [autocomplete~="address-line1"]') != null

The output will read true if autocomplete tags are present.

Add autocomplete tags​

If autocomplete tags are not present, you'll have to add them to each HTML input you'd like to autofill.

Here are common autocomplete tags for addresses. This is a non-exhaustive list.

Autocomplete tagDescriptionExample
autocomplete="address-line1"The first line of an address, usually includes the street number and street.740 15th St NW
autocomplete="address-line2"The second line of an address, usually an apartment number.Apartment 700
autocomplete="address-level1"The least specific administrative level. In the United States, this is the state or territory.District of Columbia
autocomplete="address-level2"The second least specific administrative level. In the United States, this is the city.Washington
autocomplete="address-level3"In countries with more than two administrative levels.
autocomplete="postal-code"The postal code of the administrative level.20005
autocomplete="country"The standardized country code.us
autocomplete="country-name"The country name. Note: These are non-standardized.United States

Additional Resources​

Quickstart Guides are also available for the other main features of Mapbox Search JS:

Address Autofill can also be implemented with a custom UI by using the Mapbox Search JS Core Framework.

このpageは役に立ちましたか？