Skip to main content

Geocoding

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.

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.

Components

Geocoder

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

Parameters

props(GeocoderProps) 

Example

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

Hooks

useGeocodingCore

A React hook that returns a GeocodingCore instance.

Parameters

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

Returns

GeocodingCore

Example

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

Options and Type Definitions

GeocoderProps

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 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.
            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.
                                Was this section on GeocoderProps helpful?

                                GeocoderRefType

                                Type

                                Object

                                Properties

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