Skip to main content

Search Box - Web Quickstart

Search Box is a Mapbox Search JS feature that allows users to quickly search for places, addresses, and points of interest. It is powered by the Mapbox Search Box API and can be used in a web or Node environment.

Search Box UI components can be dropped into websites as standalone elements or as part of a comprehensive map experience.

This Quickstart Guide will help you get started with Search Box using the Mapbox Search JS Web framework (using HTML Custom Elements).

To use Search Box in a React app, see the Search Box 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.0.0-beta.21/web.js"></script>

This script will give you access to Mapbox's HTML Custom Elements (<mapbox-address-autofill>,<mapbox-search-box> <mapbox-geocoder>, etc ) as well as the mapboxsearch global object. These will allow your webpage access to the Mapbox Search JS functionality.

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 the Custom Element in HTML

You can add the <mapbox-search-box> component directly to your HTML, wherever you would like the Search Box interactive input to appear. This method does not require JavaScript code after adding the library to your project.

<div>
<mapbox-search-box
access-token="YOUR_MAPBOX_ACCESS_TOKEN"
proximity="0,0"
>
</mapbox-search-box>
</div>

This will implement the Search Box UI, but additional JavaScript is necessary to handle the response when a user chooses a suggested search item. You can query the document to get the MapboxSearchBox instance, then set its properties or add an event listener to handle the response when a user selects an item from the list.

<script>
const script = document.getElementById('search-js');
// wait for the Mapbox Search JS script to load before using it
script.onload = function () {
// select the MapboxSearchBox instance
const searchBox = document.querySelector('mapbox-search-box')

// set the options property
searchBox.options = {
language: 'es',
country: 'MX'
}

// add an event listener to handle the `retrieve` event
searchBox.addEventListener('retrieve', (e) => {
const feature = e.detail;
console.log(feature) // geojson object representing the selected item
});
}
</script>

Using the Custom Element in JavaScript

You may also add the <mapbox-search-box> element to the page after it loads via JavaScript code by using the MapboxSearchBox class. You can configure its behavior by setting various properties on the element's instance before adding it to the DOM.

This method may be preferable for users who are already using a lot of JavaScript in their projects, and want to control and configure address autofill from their JavaScript code.

Implementation when using the Mapbox CDN

// add an empty div to append the search box to
<div></div>

<script>
const script = document.getElementById('search-js');
// wait for the Mapbox Search JS script to load before using it
script.onload = function () {
// instantiate a <mapbox-search-box> element using the MapboxSearchBox class
const searchBoxElement = new mapboxsearch.MapboxSearchBox()

searchBoxElement.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN'

// set the options property
searchBoxElement.options = {
language: 'es',
country: 'MX'
}

// append <mapbox-search-box> to the document
document.querySelector('div').appendChild(searchBoxElement);
};
</script>

Implementation when using a module bundler

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

// instantiate a <mapbox-search-box> element using the MapboxSearchBox class
const searchBoxElement = new MapboxSearchBox()

searchBoxElement.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN'

// set the options property
searchBoxElement.options = {
language: 'es',
country: 'MX'
}

// append <mapbox-search-box> to the document
document.querySelector('div').appendChild(searchBoxElement);

Integration with a Mapbox GL JS Map

The <mapbox-search-box> custom element can be used in a standalone fashion, but a common use case is to zoom to a location on a map and show a marker pin after the user chooses a result. <mapbox-search-box> includes convenient configuration options for binding with a Mapbox GL JS Map instance to achieve this functionality.

The bindMap() method binds to the Map instance, and the settings mapboxgl and marker are used to create the Marker.

<link href="https://api.mapbox.com/mapbox-gl-js/v3.4.0/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.4.0/mapbox-gl.js"></script>

...

<div id='search-box-container'></div>
<div id="map" style="height: 400px; width: 400px"></div>

<script>
const script = document.getElementById('search-js');
// wait for the Mapbox Search JS script to load before using it
script.onload = function () {
const mapboxAccessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';

// instantiate a map
const map = new mapboxgl.Map({
accessToken: mapboxAccessToken,
container: 'map',
center: [-74.5, 40],
zoom: 9
});

// instantiate a search box instance
const searchBox = new mapboxsearch.MapboxSearchBox()

// set the mapbox access token, search box API options
searchBox.accessToken = mapboxAccessToken
searchBox.options = {
language: 'es'
}

// set the mapboxgl library to use for markers and enable the marker functionality
searchBox.mapboxgl = mapboxgl
searchBox.marker = true

// bind the search box instance to the map instance
searchBox.bindMap(map)

// add the search box instance to the DOM
document.getElementById('search-box-container').appendChild(searchBox)
}
</script>

example
Add Search Box to a Web Map

Try out a working example showing the <mapbox-search-box> HTML custom element bound to a Mapbox GL JS map.

chevron-right

Additional Resources

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

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

Was this page helpful?