Skip to main content

Address Autofill

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

This page includes reference documentation for the Address Autofill and Address Confirmation components, hooks, and types in the Mapbox Search JS React framework.

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

Components

AddressAutofill

<AddressAutofill> is a React component that wraps an address <input> element with intelligent, location-aware autocomplete functionality.

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

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

Internally, this wraps the <mapbox-address-autofill> element.

Props

NameDescription

accessToken

string
The Mapbox access token to use for all requests.

options

Partial<AddressAutofillOptions>
Options to pass to the underlying AddressAutofillCore interface.

theme

Theme
The Theme to use for styling the autofill and confirmation dialog components.

popoverOptions

Partial<PopoverOptions>
The PopoverOptions to define popover positioning.

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.

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.

children

React.ReactChild
Children to render inside the autofill component. This must include an <input> element with either autocomplete type "street-address" or "address-line1" .

onChange

function (value: string): void
Callback for when the <input> value changes.

onSuggest

function (res: AddressAutofillSuggestionResponse): void
Fired when the user is typing in the input and provides a list of suggestions. The underlying response from AddressAutofillCore is passed.

onSuggestError

function (error: Error): void
Fired when AddressAutofillCore has errored providing a list of suggestions. The underlying error is passed.

onRetrieve

function (res: AddressAutofillRetrieveResponse): void
Fired when the user has selected a suggestion, before the form is autofilled. The underlying response from AddressAutofillCore is passed.

interceptSearch

function (value: string): string
A callback providing the opportunity to validate and/or manipulate the input text before it triggers a search, for example by using a regular expression. If a truthy string value is returned, it will be passed into the underlying search API. If null , undefined or empty string is returned, no search request will be performed.

Example

import { AddressAutofill } from '@mapbox/search-js-react'
export function Component() {
  const [value, setValue] = React.useState('');

  const handleChange = (e) => {
    setValue(e.target.value);
  };

  return (
    <form>
      <AddressAutofill accessToken={'YOUR_MAPBOX_ACCESS_TOKEN'}>
        <input
          autoComplete="shipping address-line1"
          value={value}
          onChange={handleChange}
        />
      </AddressAutofill>
    </form>
  );
}
Was this section on AddressAutofill helpful?

Hooks

useAddressAutofillCore

A React hook that returns a AddressAutofillCore instance.

Parameters

NameDescription

options

AddressAutofillOptions

options.accessToken

string
Your Mapbox access token.

Returns

AddressAutofillCore

Example

import { useAddressAutofillCore } from '../src';
const autofill = useAddressAutofillCore({ accessToken: 'YOUR_MAPBOX_ACCESS_TOKEN' });
const response = await autofill.suggest('1600 pennsylvania ave nw', {
  sessionToken: 'test-123'
});
console.log(response);
// { suggestions: [...], attribution: '...' };
Was this section on useAddressAutofillCore helpful?

useConfirmAddress

A React hook that returns a form ref and a function to show the address confirmation modal

Parameters

NameDescription

optionsArg

AddressConfirmOptions(default {})

Returns

UseConfirmAddressObject

Example

import { useConfirmAddress } from '@mapbox/search-js-react';

export function Autofill(): React.ReactElement {
  const { formRef, showConfirm } = useConfirmAddress({
    footer: 'My custom footer'
  });

  const handleSubmit = React.useCallback(async () => {
    const result = await showConfirm();
     console.log(result);
  }, [showConfirm]);

  return (
    <div>
      <form
        ref={formRef}
        style={{ display: 'flex', flexDirection: 'column', marginTop: 30 }}
      >
        <AddressAutofill
          ...
        >
    </div>
  );
}
Was this section on useConfirmAddress helpful?

Types

AddressAutofillRefType

Methods available on a ref when attached to the AddressAutofill component.

Type

Object

Properties

NameDescription

focus

any
Was this section on AddressAutofillRefType helpful?

AddressAutofillOptions

Options used by AddressAutofillCore and useAddressAutofillCore to control the location, language, country, and limit of results. All properties are optional.

Type

Object

Properties

NameDescription

bbox

(string | LngLatBoundsLike)
Limit results to only those contained within the supplied bounding box.

country

string
An ISO 3166 alpha-2 country code to be returned. If not specified, results will not be filtered by country.

language

string
The IETF language tag to be returned. If not specified, en will be used.

limit

(string | number)
The number of results to return, up to 10 .

proximity

(string | LngLatLike)
Bias the response to favor results that are closer to this location. Provide a point coordinate provided as a LngLatLike , or use the string ip to use the requester's IP address.

streets

(string | boolean)
If enabled, street results may be returned in addition to addresses. Defaults to true .
Was this section on AddressAutofillOptions helpful?

AddressConfirmOptions

Object defining options for Address Autofill API, UI, form parsing, and address comparison

Type

Object

Properties

NameDescription

accessToken

string
Mapbox access token used for the Address Autofill and Static Image APIs
(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?

PopoverOptions

Options controlling the display of the Popover used in AddressAutofill, MapboxSearchBox, and MapboxGeocoder.

Type

Object

Properties

NameDescription

flip

boolean
If true, the popover will flip to the opposite side of the reference element to try to keep it in view when scrolling out of frame. Defaults to false.

offset

number
The distance gap between the popover and the reference element. Defaults to 5px.

placement

("top-start" | "bottom-start")
Positions the popover above or below the reference element. Defaults to 'bottom-start'.
Was this section on PopoverOptions helpful?

AddressAutofillSuggestion

An AddressAutofillSuggestion object represents a suggestion result from the Mapbox Address Autofill API.

Suggestion objects are "part one" of the two-step interactive autofill experience. Suggestion objects do not include geographic coordinates.

To get the coordinates of the result, use AddressAutofillCore#retrieve.

For tracking purposes, it is useful for any follow-up requests based on this suggestion to include same SessionToken as the original request.

Type

Object

Properties

NameDescription

accuracy

string
A point accuracy metric for the returned address feature. Can be one of rooftop , parcel , point , interpolated , intersection , street .

action

{id: string}
Action block of the suggestion result. contains id to execute retrieve

address_level1

string
Address level 1 from the WHATWG Autocomplete Specification

address_level2

string
Address level 2 from the WHATWG Autocomplete Specification

address_level3

string
Address level 3 from the WHATWG Autocomplete Specification

address_line1

string
Address line 1 from the WHATWG Autocomplete Specification

address_line2

string
Address line 2 from the WHATWG Autocomplete Specification

address_line3

string
Address line 3 from the WHATWG Autocomplete Specification

context

Array<AddressAutofillFeatureContextComponent>
An array of context objects representing the hierarchy of encompassing parent features for a given feature.

country

string
Long form country name, for example: "United States"

country_code

string
The short form country name, for example: "us". This follows the ISO 3166 alpha-2 country code specification.

description

string
Additional details, such as city and state for addresses.

feature_name

string
The name of the feature.

full_address

string
The full address of the suggestion.

language

string
The IETF language tag of the feature.

maki

string
The name of the Maki icon associated with the feature.

mapbox_id

string
Feature id. The mapbox_id uniquely identifies a feature in the Mapbox search database.

match_code

MatchCode
An object describing the level of confidence that the given response feature matches the address intended by the request query. Includes boolean flags denoting matches for each address sub-component.

matching_name

string
The feature name, as matched by the search algorithm.

metadata

{iso_3166_1: string}
Address metadata fields of the feature.

Includes the short form country name, for example: "us". This follows the ISO 3166 alpha-2 country code specification.

place_name

string
A string representing the feature in the requested language, if specified, and its full result hierarchy.

place_type

Array<string>
An array of strings representing the geographic feature type of the feature. Possible values include "address" and "secondary_address".

postcode

string
Postal code.

Example

const autofill = new AddressAutofillCore({ accessToken: 'pk.my-mapbox-access-token' });

const sessionToken = new SessionToken();
const result = await search.autofill('Washington D.C.', { sessionToken });
if (result.suggestions.length === 0) return;

const suggestion = result.suggestions[0];
const { features } = await autofill.retrieve(suggestion, { sessionToken });
doSomethingWithCoordinates(features);
Was this section on AddressAutofillSuggestion helpful?

AddressAutofillFeatureSuggestion

An AddressAutofillFeatureSuggestion object represents GeoJSON suggestion results from the Mapbox Address Autofill API.

As per the Mapbox Address Autofill API, this will always be Point.

Type

any

Example

const featureSuggestion = {
  type: 'Feature',
  geometry: {
    type: 'Point',
    coordinates: [0,0]
  },
  properties: {
    feature_name: 'Washington D.C.',
  }
};

Static Members

Was this section on AddressAutofillFeatureSuggestion helpful?

AddressAutofillSuggestionResponse

Response object returned when calling the suggest method of AddressAutofillCore

Type

Object

Properties

NameDescription

attribution

string
The attribution data for results.

suggestions

Array<AddressAutofillSuggestion>
The returned suggestion objects.
Was this section on AddressAutofillSuggestionResponse helpful?

AddressAutofillRetrieveResponse

Response object returned when calling the retrieve method of AddressAutofillCore

Type

Object

Properties

NameDescription

attribution

string
The attribution data for results.

features

Array<AddressAutofillFeatureSuggestion>
The returned feature objects.
Was this section on AddressAutofillRetrieveResponse helpful?

AddressAutofillFeatureContextComponent

Object representing one level of hierarcy among encompassing parent features for a given AddressAutofillSuggestion.

Type

Object

Properties

NameDescription

id

string
An identifier prefixed with the component type, for example country.123 .

mapbox_id

string
The unique Mapbox ID of the context feature.

text

string
A string representing the feature in the requested language, if specified.

wikidata_id

string
The Wikidata identifier for the returned feature.
Was this section on AddressAutofillFeatureContextComponent helpful?

LngLatLike

A LngLat object, an array of two numbers representing longitude and latitude, or an object with lng and lat or lon and lat properties.

Type

(LngLat | [number, number] | {lng: number, lat: number} | {lon: number, lat: number})

Example

const v1 = new LngLat(-122.420679, 37.772537);
const v2 = [-122.420679, 37.772537];
const v3 = {lon: -122.420679, lat: 37.772537};
Was this section on LngLatLike helpful?

LngLatBoundsLike

A LngLatBounds object, an array of LngLatLike objects in [sw, ne] order, or an array of numbers in [west, south, east, north] order.

Type

(LngLatBounds | [LngLatLike, LngLatLike] | [number, number, number, number])

Example

const v1 = new LngLatBounds(
  new LngLat(-73.9876, 40.7661),
  new LngLat(-73.9397, 40.8002)
);
const v2 = new LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
const v3 = [[-73.9876, 40.7661], [-73.9397, 40.8002]];
Was this section on LngLatBoundsLike helpful?

ConfirmationMinimapOptions

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

Type

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?

ValidationOptions

Type

Object

Properties

NameDescription

bbox

(string | LngLatBoundsLike)
Limit results to only those contained within the supplied bounding box.

country

string
An ISO 3166 alpha-2 country code to be returned.

If not specified, results will not be filtered by country.

language

string
The IETF language tag to be returned.

If not specified, en will be used.

proximity

(string | LngLatLike)
Bias the response to favor results that are closer to this location.

When both ValidationOptions#proximity and ValidationOptions#origin are specified, origin is interpreted as the target of a route, while proximity indicates the current user location.

Was this section on ValidationOptions helpful?

MatchCode

An object describing the level of confidence that the given response feature matches the address intended by the request query.

Type

Object

Properties

NameDescription

address_number

MatchCodeType
An indication of how well the address_number component of the feature matches the query.

confidence

MatchCodeConfidence
An overall confidence level for how well the feature matches the query.

country

MatchCodeType
An indication of how well the country component of the feature matches the query.

locality

MatchCodeType
An indication of how well the locality component of the feature matches the query.

place

MatchCodeType
An indication of how well the place component of the feature matches the query.

postcode

MatchCodeType
An indication of how well the postcode component of the feature matches the query.

region

MatchCodeType
An indication of how well the region component of the feature matches the query.

secondary_address

MatchCodeType
An indication of how well the secondary_address component of the feature matches the query.

street

MatchCodeType
An indication of how well the street component of the feature matches the query.
Was this section on MatchCode helpful?
Was this page helpful?