Geocoding

Geocoding is a custom HTML element that renders a UI search component, allowing users to forward and reverse geocode search and control a Mapbox GL JS map.

This page includes reference documentation for the MapboxGeocoder element, part of the Mapbox Search JS Web framework.

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

HTML Custom Element

MapboxGeocoder

MapboxGeocoder, also available as the element <mapbox-geocoder>, is an element that lets you search for addresses and places using the Mapbox Geocoding API.

It can control a Mapbox GL JS map to zoom to the selected result.

Additionally, MapboxGeocoder implements the IControl interface.

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

new MapboxGeocoder()

Example

const search = new MapboxGeocoder();
search.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
map.addControl(search);
<mapbox-geocoder
  access-token="YOUR_MAPBOX_ACCESS_TOKEN"
  proximity="0,0"
>
</mapbox-geocoder>

Instance Members

The <input> element wrapped by the MapboxGeocoder component.

Type
HTMLInputElement

The Mapbox access token to use for all requests.

Example
search.accessToken = 'pk.my-mapbox-access-token';

The value of the input element.

Example
console.log(search.value);

Options to pass to the underlying GeocodingCore interface.

Type
GeocodingOptions
Example
search.options = {
 language: 'en',
 country: 'US',
};

Options defining the behavior of web component or its underlying search functionality. Distinct from the GeocodingOptions options, these do not correspond to the core API specification.

Type
MapboxGeocoderComponentOptions
Example
search.componentOptions = {
 flipCoordinates: true,
 flyTo: true
};

The Theme to use for styling the suggestion box and geocoder input box.

Type
Theme
Example
search.theme = {
  variables: {
    colorPrimary: 'myBrandRed'
  },
  cssText: ".Input:active { opacity: 0.9; }"
};

The PopoverOptions to define popover positioning.

Type
PopoverOptions
Example
search.popoverOptions = {
  placement: 'top-start',
  flip: true,
  offset: 5
};

The input element's placeholder text. The default value may be localized if GeocodingOptions#language is set.

Type
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
Enable search only when the input value length is more than 3 characters.

search.interceptSearch = (val) => val?.length > 3 ? val : null;

Map settings

A mapbox-gl instance to use when creating Markers. Required if MapboxGeocoder#marker is true.

If true, a Marker will be added to the map at the location of the user-selected result using a default set of Marker options. If the value is an object, the marker will be constructed using these options. If false, no marker will be added to the map. Requires that MapboxGeocoder#mapboxgl also be set.

Type
(boolean | mapboxgl.MarkerOptions)
Example
search.marker = {
  color: 'red',
  draggable: true
};

Methods

Focuses the input element.

Returns
void

Sets the input text and triggers a search programmatically

Parameters
NameDescription
text string 
Returns
void

Map binding

Connects the Geocoder to a Map, which handles both setting proximity and zoom after a suggestion click.

Parameters
NameDescription
map mapboxgl.Map 
Returns
void
Example
const search = new MapboxGeocoder();
search.bindMap(map);

Unbinds the Geocoder from a Map.

Returns
void

Events

Fired when the user is typing and is provided a list of suggestions.

The underlying response from GeocodingCore is passed as the event's detail.

Type
GeocodingResponse
Example
search.addEventListener('suggest', (event) => {
  const suggestions = event.detail.suggestions;
  // ...
});

Fired when GeocodingCore has errored providing a list of suggestions.

The underlying error is passed as the event's detail.

Type
Error
Example
search.addEventListener('suggesterror', (event) => {
  const error = event.detail;
  // ...
});

Fired when the user has selected a suggestion.

The underlying response from GeocodingCore is passed as the event's detail.

Type
GeocodingFeature
Example
search.addEventListener('retrieve', (event) => {
  const feature = event.detail;
  // ...
});

Fired when the user has changed the <input> text.

The new input value is passed as the event's detail.

Type
string
Example
search.addEventListener('input', (event) => {
  if (e.target !== e.currentTarget) return;
  const searchText = event.detail;
  // ...
});

Fired when the user has cleared the box, either by deleting all text or clicking the "Clear" icon.

Example
search.addEventListener('clear', () => {
  console.log('search box cleared');
  // ...
});

Fired when the user moved focus away from the MapboxGeocoder component.

Example
search.addEventListener('blur', () => {
  console.log('search box blurred');
  // ...
});
Was this section on MapboxGeocoder helpful?YesNo

MapboxGeocoderComponentOptions

Options to configure component-specific Search behavior

Type

Object

Properties

NameDescription
customSearch function (text: string): Promise<Array<GeocodingFeature>> A function accepting the query string which performs supplemental search results on top of those from the Mapbox Geocoding API. Expected to return a Promise which resolves to an array of GeoJSON-like Features as described in the Mapbox Geocoding API .
flipCoordinates boolean If true, the coordinates in the query string are expected to be (lat,lng) instead of (lng,lat).
flyTo (mapboxgl.FlyToOptions | boolean) If false , animating the map to a selected result is disabled. If true (default), animating the map will use the default animation parameters. If an object, it will be passed as options to the map flyTo method.
Was this section on MapboxGeocoderComponentOptions helpful?YesNo