Geocoding provides a rich UI search component, allowing users to forward and reverse geocode search and control a Mapbox GL JS map.
This page includes reference documentation for the Geocoding components and hooks in the Mapbox Search JS React framework.
For installation instructions and a helpful introduction to using Geocoding in your React app, see our React Search Box Quickstart Guide.
<Geocoder> is a React component that provides an interactive geocoder,
powered by the Mapbox Geocoding API.
To use this element, you must have a Mapbox access token.
Internally, this wraps the <mapbox-geocoder> element.
| Name | Description |
|---|---|
| props GeocoderProps |
import { Geocoder } from "@mapbox/search-js-react";
export function Component() {
const [value, setValue] = React.useState('');
const handleChange = (d) => {
setValue(d);
};
return (
<Geocoder
options={{
proximity: {
lng: -122.431297,
lat: 37.773972,
},
}}
value={value}
onChange={handleChange}
accessToken="YOUR_MAPBOX_ACCESS_TOKEN"
/>
);
}A React hook that returns a GeocodingCore instance.
| Name | Description |
|---|---|
| options GeocodingOptions | |
| options.accessToken string | Your Mapbox access token. |
import { useGeocodingCore } from '@mapbox/search-js-react';
const geocodingCore = useGeocodingCore({ accessToken: 'YOUR_MAPBOX_ACCESS_TOKEN' });
const response = await geocodingCore.forward('1600 pennsylvania ave nw', {
limit: 1
});
console.log(response);
// { type: 'FeatureCollection', features: [...], attribution: '...', url: '...' };Props for the Geocoder component
| Name | Description |
|---|---|
| accessToken string | The Mapbox access token to use for all requests. |
| componentOptions Partial<MapboxGeocoderComponentOptions> | 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
GeocoderProps#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
GeocoderProps#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: GeocodingFeature): void | Fired when the user has selected a suggestion. The underlying feature from GeocodingCore is passed. |
| onSuggest function (res: GeocodingResponse): void | Fired when the user is typing in the input and provides a list of suggestions. The underlying response from GeocodingCore is passed. |
| onSuggestError function (error: Error): void | Fired when GeocodingCore has errored providing a list of suggestions. The underlying error is passed. |
| options Partial<GeocodingOptions> | Options to pass to the underlying GeocodingCore interface. |
| placeholder string | The input element's placeholder text. The default value may be localized if GeocodingOptions#language is set. |
| popoverOptions Partial<PopoverOptions> | The PopoverOptions to define popover positioning. |
| theme Theme | The Theme to use for styling the geocoder. |
| value string | Value to display in the geocoder. |