Search Box | Mapbox Search JS

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 the Search Box components and hooks in the Mapbox Search JS React framework.

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

Name	Description
accessToken `string`	The Mapbox access token to use for all requests.
options `Partial<SearchBoxOptions>`	Options to pass to the underlying SearchBoxCore interface.
componentOptions `Partial<MapboxSearchBoxComponentOptions>`	Options defining the behavior of web component or its underlying search functionality.
theme `Theme`	The Theme to use for styling the search box.
popoverOptions `Partial<PopoverOptions>`	The PopoverOptions to define popover positioning.
placeholder `string`	The input element's placeholder text. The default value may be localized if SearchBoxOptions#language is set.
map `mapboxgl.Map`	If specified, the map will be centered on the retrieved suggestion.
marker `(boolean \| mapboxgl.MarkerOptions)`	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 SearchBoxProps#mapboxgl also be set.
mapboxgl `any`	A mapbox-gl instance to use when creating Markers . Required if SearchBoxProps#marker is `true` .
value `string`	Value to display in the search box.
onChange `function (value: string): void`	Callback for when the value changes.
onSuggest `function (res: SearchBoxSuggestionResponse): void`	Fired when the user is typing in the input and provides a list of suggestions. The underlying response from SearchBoxCore is passed.
onSuggestError `function (error: Error): void`	Fired when SearchBoxCore has errored providing a list of suggestions. The underlying error is passed.
onRetrieve `function (res: SearchBoxRetrieveResponse): void`	Fired when the user has selected a suggestion. The underlying response from SearchBoxCore is passed.
onClear `function (): void`	Fired when the user has cleared the search box.
onBlur `function (): void`	Fired when the user has blurred the search box.
interceptSearch `function (value: string): 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.

Hooks

useSearchBoxCore

A React hook that returns a SearchBoxCore instance.

Parameters

Name	Description
options `SearchBoxOptions`
options.accessToken `string`	Your Mapbox access token.

Example


import { useSearchBoxCore } from '@mapbox/search-js-react';
const searchBoxCore = useSearchBoxCore({ accessToken: 'YOUR_MAPBOX_ACCESS_TOKEN' });
const response = await searchBoxCore.suggest('1600 pennsylvania ave nw', {
  sessionToken: 'test-123'
});
console.log(response);
// { suggestions: [...], attribution: '...', url: '...' };

SearchBoxCore

Was this section on useSearchBoxCore helpful?

useSearchSession

A React hook that returns a SearchSession instance.

Parameters

Name	Description
search `(SearchBoxCore \| AddressAutofillCore)`

Returns

SearchSession:

SearchSession

Was this section on useSearchSession helpful?

Types

SearchBoxRefType

Methods available on a ref when attached to the SearchBox component.

Properties

Name	Description
focus `any`
search `any`

Was this section on SearchBoxRefType helpful?

SearchBoxOptions

Options object for configuring SearchBoxCore, mapped to Search Box API parameters.

Properties

Name	Description
bbox `(string \| LngLatBoundsLike)`	Limit results to only those contained within the supplied bounding box.
country `string`	An ISO 3166 alpha-2 country code to be returned. If not specified, results will not be filtered by country.
eta_type `"navigation"`	Used to estimate the time of arrival from the location specified in SearchBoxOptions#origin . The only allowed value for this parameter is navigation. This parameter, along with SearchBoxOptions#origin and SearchBoxOptions#navigation_profile, is required for ETA calculations. ETA calculations will incur additional latency.
language `string`	The IETF language tag to be returned. If not specified, `en` will be used.
limit `(string \| number)`	The number of results to return, up to `10` .
navigation_profile `("driving" \| "walking" \| "cycling")`	The navigation routing profile to use for distance/eta calculations. For distance calculations, both SearchBoxOptions#navigation_profile and SearchBoxOptions#origin must be specified. For ETA calculations: SearchBoxOptions#navigation_profile, SearchBoxOptions#origin, and SearchBoxOptions#eta_type must be specified.
origin `(string \| LngLatLike)`	The location from which to calculate distance. This parameter may incur additional latency. When both SearchBoxOptions#proximity and SearchBoxOptions#origin are specified, `origin` is interpreted as the target of a route, while `proximity` indicates the current user location. For distance calculations, both SearchBoxOptions#navigation_profile and SearchBoxOptions#origin must be specified. For ETA calculations: SearchBoxOptions#navigation_profile, SearchBoxOptions#origin, and SearchBoxOptions#eta_type must be specified.
poi_category `string`	Limit results to those that belong to one or more categories, provided as a comma-separated list.
poi_category_exclusions `string`	A comma-separated list of canonical category names that limits POI results to those that are not part of the given categories.
proximity `(string \| LngLatLike)`	Bias the response to favor results that are closer to this location. When both SearchBoxOptions#proximity and SearchBoxOptions#origin are specified, `origin` is interpreted as the target of a route, while `proximity` indicates the current user location.
rich_metadata_provider `string`	A comma-separated list of rich metadata providers to include in a suggestion result.
route `string`	A polyline encoded linestring describing the route to be used for searching. Both polyline5 and polyline6 precision are accepted, but must be specified using the SearchBoxOptions#route_geometry parameter.
route_geometry `string`	Passed in conjunction with a route polyline describing its precision. Options are polyline or polyline6. If this parameter is not provided with a SearchBoxOptions#route , the default is polyline. Accurate results depend on including the correct route_geometry for the SearchBoxOptions#route provided.
sar_type `string`	This indicates that the user intends to perform a higher cost search-along-route request. This should be included when SearchBoxOptions#route is included and should have a value of isochrone.
time_deviation `(string \| number)`	Maximum detour in estimated minutes from route.
types `(string \| Set<SearchBoxAdministrativeUnitTypes>)`	Limit results to one or more types of features. If no types are specified, all possible types may be returned. Reference: https://docs.mapbox.com/api/search/search-box/#administrative-unit-types

Was this section on SearchBoxOptions helpful?

SearchBoxSuggestionResponse

A SearchBoxSuggestionResponse object represents a returned data object from the suggest endpoint of the Mapbox Search Box API.

Properties

Name	Description
attribution `string`	The attribution data for results.
suggestions `Array<SearchBoxSuggestion>`	The returned suggestion objects.

Was this section on SearchBoxSuggestionResponse helpful?

SearchBoxRetrieveResponse

A SearchBoxRetrieveResponse object represents a returned data object from the /retrieve endpoint of the Mapbox Search Box API.

Properties

Name	Description
attribution `string`	The attribution data for results.
features `Array<SearchBoxFeatureSuggestion>`	The returned feature objects.

Was this section on SearchBoxRetrieveResponse helpful?

SearchBoxSuggestion

A SearchBoxSuggestion object represents a suggestion result from the Mapbox Search Box API.

SearchBoxSuggestion objects are "part one" of the two-step interactive search experience, and include useful information about the result, such as: SearchBoxSuggestion#name, SearchBoxSuggestion#full_address, and SearchBoxSuggestion#maki.

SearchBoxSuggestion objects do not include geographic coordinates. To get the coordinates of the result, use SearchBoxCore#retrieve.

For tracking purposes, it is useful for any follow-up requests based on this suggestion to include same SessionToken as the original request.

Reference: https://docs.mapbox.com/api/search/search-box/#response-get-suggested-results

Type

Object

Properties

Name	Description
added_distance `number`	The distance added to an input route by including the given suggestion, in meters.
added_time `number`	The estimated time added to an input route by including the given suggestion, in minutes.
address `string`	The address of the result containing the address number and street.
brand `string`	The brand name of the result, if it is a POI and is applicable.
brand_id `string`	The canonical brand ID of the result, if it is a POI and is applicable.
context `SuggestionJSONContext`	The context of the feature. This context has layers that follow the Administrative unit types .
distance `number`	An approximate distance to the `origin` location, in meters. Only provided when `origin` and `navigation_profile` are used in the request.
eta `number`	The estimated time of arrival from the origin point to the feature, in minutes. Only provided when `eta_type` , `origin` , and `navigation_profile` are used in the request. If an address is not on the road network, an ETA will not be provided.
external_ids `any`	An object containing the IDs of the feature found in external databases, with the keys being the data source names and the values being the IDs.
feature_type `string`	The type of the result. For POIs, this will be `poi` . For categories, this will be `category` . For address-type results, the global context hierarchy is used ( `country` , `region` , `postcode` , `district` , `place` , `locality` , `neighborhood` , `address` ). See the Administrative unit types section for details about these types.
full_address `string`	The full address of the result, which concatenates SearchBoxSuggestion#address and SearchBoxSuggestion#place_formatted .
language `string`	An IETF language tag indicating the language of the result.
maki `string`	A string representing an associated Maki icon to use for this result.
mapbox_id `string`	The id to use with SearchBoxCore#retrieve to obtain full feature details.
metadata `any`	An object containing additional metadata for the feature, if applicable.
name `string`	The name of the feature.
name_preferred `string`	The preferred name of the feature, if different than SearchBoxSuggestion#name .
place_formatted `string`	A formatted string of result context comprised of the place, region, country, and postcode.
poi_category `Array<string>`	An array including the POI categories the result falls into, if it is a POI.

Example


const search = new SearchBoxCore({ accessToken: 'pk.my-mapbox-access-token' });

const sessionToken = new SessionToken();
const result = await search.suggest('Washington D.C.', { sessionToken });
if (result.suggestions.length === 0) return;

const suggestion = result.suggestions[0];

const { features } = await search.retrieve(suggestion, { sessionToken });
doSomethingWithCoordinates(features);

Was this section on SearchBoxSuggestion helpful?

SuggestionJSONContext

Raw JSON form of a suggestion result's "context" from the Mapbox Search Box API.

Reference: https://docs.mapbox.com/api/search/search-box/#response-get-suggested-results

Type

Object

Properties

Name	Description
address `ContextEntry`	The address of the result including the address number and street
address_number `ContextEntry`	The address number of the result
country `any`	The country of the result
district `ContextEntry`	The district of the result
locality `ContextEntry`	The locality of the result
neighborhood `ContextEntry`	The neighborhood of the result
place `ContextEntry`	The place of the result
postcode `ContextEntry`	The postcode of the result
region `any`	The region of the result
street `ContextEntry`	The street of the result

Was this section on SuggestionJSONContext helpful?

SearchBoxFeatureSuggestion

A SearchBoxFeatureSuggestion object represents a GeoJSON suggestion result from the Mapbox Search Box API.

Feature suggestions are "part two" of the two-step interactive search experience and includes geographic coordinates. Multiple feature suggestions may be returned from a single search query, for example in an airport with multiple terminals.

As per the Mapbox Search Box API, this will always be Point.

Legal terms:

The Mapbox Terms of Service states any rendering of a feature suggestion must be using Mapbox map services (for example, displaying results on Google Maps or MapKit JS is not allowed).

Disclaimer:

The failure of Mapbox to exercise or enforce any right or provision of these Terms will not constitute a waiver of such right or provision.

Type

any

Example


const featureSuggestion = {
  type: 'Feature',
  geometry: {
    type: 'Point',
    coordinates: [0,0]
  },
  properties: {
    name: 'Washington D.C.',
  }
};

Response: Retrieve feature

Was this section on SearchBoxFeatureSuggestion helpful?

SearchBoxAdministrativeUnitTypes

Administrative unit types for the Mapbox Search Box API.

Type

("country" | "region" | "postcode" | "district" | "place" | "locality" | "neighborhood" | "street" | "address" | "block")

https://docs.mapbox.com/api/search/search-box/#administrative-unit-types

Was this section on SearchBoxAdministrativeUnitTypes helpful?

Name	Description
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.

Was this section on MapboxSearchBoxComponentOptions helpful?

Name	Description
flip `boolean`	If true, the popover will flip to the opposite side of the reference element to try to keep it in view when scrolling out of frame. Defaults to false.
offset `number`	The distance gap between the popover and the reference element. Defaults to 5px.
placement `("top-start" \| "bottom-start")`	Positions the popover above or below the reference element. Defaults to 'bottom-start'.

Was this section on PopoverOptions helpful?

Was this page helpful?