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.24/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>