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.
<SearchBox> is a React component that provides an interactive search box,
powered by the Mapbox Search Box API.
To use this element, you must have a Mapbox access token.
Internally, this wraps the <mapbox-search-box> element.
| Name | Description |
|---|---|
| props SearchBoxProps |
import { SearchBox } from "@mapbox/search-js-react";
export function Component() {
const [value, setValue] = React.useState('');
const handleChange = (d) => {
setValue(d);
};
return (
<SearchBox
options={{
proximity: {
lng: -122.431297,
lat: 37.773972,
},
}}
value={value}
onChange={handleChange}
accessToken="YOUR_MAPBOX_ACCESS_TOKEN"
/>
);
}A React hook that returns a SearchBoxCore instance.
| Name | Description |
|---|---|
| options SearchBoxOptions | |
| options.accessToken string | Your Mapbox access token. |
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: '...' };A React hook that returns a SearchSession instance.
| Name | Description |
|---|---|
| search (SearchBoxCore | AddressAutofillCore) |
Props for the SearchBox component
| Name | Description |
|---|---|
| accessToken string | The Mapbox access token to use for all requests. |
| componentOptions Partial<MapboxSearchBoxComponentOptions> | Options defining the behavior of web component or its underlying search functionality. |
| 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.
|
| map mapboxgl.Map | If specified, the map will be centered on the retrieved suggestion. |
| mapboxgl any | A
mapbox-gl
instance to use when creating
Markers
. Required if
SearchBoxProps#marker
is
true
.
|
| 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.
|
| onBlur function (): void | Fired when the user has blurred the search box. |
| onChange function (value: string): void | Callback for when the value changes. |
| onClear function (): void | Fired when the user has cleared the search box. |
| onRetrieve function (res: SearchBoxRetrieveResponse): void | Fired when the user has selected a suggestion. The underlying response from SearchBoxCore is passed. |
| 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. |
| options Partial<SearchBoxOptions> | Options to pass to the underlying SearchBoxCore interface. |
| placeholder string | The input element's placeholder text. The default value may be localized if SearchBoxOptions#language is set. |
| popoverOptions Partial<PopoverOptions> | The PopoverOptions to define popover positioning. |
| theme Theme | The Theme to use for styling the search box. |
| value string | Value to display in the search box. |