メインコンテンツまでスキップ

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 Mapbox Search JS Web.

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.5.0/web.js"></script>

This script will give you access to Mapbox Search JS Web classes (MapboxAddressAutofill,MapboxSearchBox MapboxGeocoder, etc ) as well as the mapboxsearch global object.

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'

MapboxSearchBox is a JavaScript class. Instantiating it produces a DOM element you can append anywhere in your document, or pass to a Mapbox GL JS map via map.addControl().

To use MapboxSearchBox instantiate the class, add your access token (required), configure it with the available parameters (optional) and append it to the DOM.

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

// instantiate a new MapboxSearchBox
const searchBoxElement = new MapboxSearchBox()

searchBoxElement.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN'

// set options for language & country
searchBoxElement.options = {
  language: 'es',
  country: 'MX'
}

// append to the DOM - (adjust as necessary for your document)
document.querySelector('div').appendChild(searchBoxElement);

Integration with a Mapbox GL JS Map​

MapboxSearchBox 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. MapboxSearchBox includes convenient configuration options for binding with a Mapbox GL JS Map instance to achieve this functionality.

import mapboxgl from 'mapbox-gl'
import { MapboxSearchBox } from '@mapbox/search-js-web'
import 'mapbox-gl/dist/mapbox-gl.css'

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 new search box instance
const searchBox = new MapboxSearchBox()

// set the mapbox access token and 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

// add the search box instance to the Map Control interface
map.addControl(searchBox)
EXAMPLE
Add Search Box to a Web Map

Try out a working example showing the MapboxSearchBox bound to a Mapbox GL JS map.

Working with events​

While MapboxSearchBox works seamlessly when implemented with a Mapbox GL JS map, there are many cases when you will want to add in additional functionality to SearchBox or trigger other code on MapboxSearchBox interactions. MapboxSearchBox provides many events which allow you to listen to and extend functionality. See the API Reference for a full list.

Below is an example of a retrieve event which logs the selected suggestion.

const searchBox = new MapboxSearchBox();
...

// 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
});

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.

このpageは役に立ちましたか？