Skip to main content

Search Box

Additional Developer Resources
Public beta for Mapbox Search JS
Mapbox Search JS is in public beta. During the public beta phase, frameworks may be subject to potential changes as they stabilize.

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.

Components

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

Parameters

props(SearchBoxProps) 

Example

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"
    />
  );
}
Was this section on SearchBox helpful?

Hooks

useSearchBoxCore

A React hook that returns a SearchBoxCore instance.

Parameters

options(SearchBoxOptions) 
NameDescription
options.accessToken
string		Your Mapbox access token.

Returns

SearchBoxCore

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: '...' };
Was this section on useSearchBoxCore helpful?

useSearchSession

A React hook that returns a SearchSession instance.

Parameters

search((SearchBoxCore | AddressAutofillCore)) 

Returns

SearchSession:
Was this section on useSearchSession helpful?

Options and Type Definitions

SearchBoxProps

Type

Object

Properties

accessToken(string): The Mapbox access token to use for all requests.
    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.
            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.
                                Was this section on SearchBoxProps helpful?

                                SearchBoxRefType

                                Type

                                Object

                                Properties

                                focus(any)
                                  search(any)
                                    Was this section on SearchBoxRefType helpful?
                                    Additional Developer Resources
                                    Was this page helpful?