Search Box

Search Box provides a rich UI for single-box location search, allowing your users to search for addresses and points of interest by place name, address, or category.

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

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

HTML Custom Element

MapboxSearchBox

MapboxSearchBox, also available as the element <mapbox-search-box>, is an element that lets you search for places, addresses, and landmarks using the Mapbox Search Box API.

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

Additionally, MapboxSearchBox implements the IControl interface.

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

new MapboxSearchBox()

Example

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

Instance Members

The <input> element wrapped by the MapboxSearchBox 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);

API-specific options to pass to the underlying SearchBoxCore interface.

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

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

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

The Theme to use for styling the suggestion box and search 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 SearchBoxOptions#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 MapboxSearchBox#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 MapboxSearchBox#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 search box 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 MapboxSearchBox();
search.bindMap(map);

Unbinds the search box from a Map.

Returns
void

Events

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

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

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

Fired when SearchBoxCore 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 SearchBoxCore is passed as the event's detail.

Type
SearchBoxRetrieveResponse
Example
search.addEventListener('retrieve', (event) => {
  const featureCollection = 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 MapboxSearchBox component.

Example
search.addEventListener('blur', () => {
  console.log('search box blurred');
  // ...
});
このsection on MapboxSearchBoxは役に立ちましたか？YesNo

MapboxSearchBoxComponentOptions

Options to configure component-specific Search behavior

Type

Object

Properties

NameDescription
allowReverse boolean Allow the user to query a coordinate string (e.g. "lng,lat") to get a reverse search result.
customSearch function (text: string): Promise<Array<SearchBoxSuggestion>> A function accepting the query string which performs supplemental search results on top of those from the Mapbox Search Box API. Expected to return a Promise which resolves to an array of suggestions as described in the Mapbox Search Box API . Additionally, each suggestion must include a _geometry property matching the "geometry" object format specified in the retrieved Feature format.
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.
このsection on MapboxSearchBoxComponentOptionsは役に立ちましたか？YesNo