> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/mapbox-search-js/llms.txt)

# Geocoding

**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](https://docs.mapbox.com/mapbox-search-js/guides/geocoding/react).

## 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](https://www.mapbox.com/help/create-api-access-token/).

#### Props

<table class="table table--fixed table--compact" style="width:100%;table-layout:fixed"><colgroup><col width="28%"><col></colgroup><thead><tr class="bg-gray-faint"><th style="border-top-left-radius:4px">Name</th><th style="border-top-right-radius:4px">Description</th></tr></thead><tbody><tr><td><strong>accessToken</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>The <a href="https://docs.mapbox.com/help/glossary/access-token/">Mapbox access token</a> to use for all requests.</span></td></tr><tr><td><strong>options</strong>&nbsp;<span>Partial&lt;<a href="#geocodingoptions">GeocodingOptions</a>&gt;</span>&nbsp;</td><td><span>Options to pass to the underlying <a href="/mapbox-search-js/api/core/geocoding/#geocodingcore">GeocodingCore</a> interface.</span></td></tr><tr><td><strong>componentOptions</strong>&nbsp;<span>Partial&lt;<a href="#mapboxgeocodercomponentoptions">MapboxGeocoderComponentOptions</a>&gt;</span>&nbsp;</td><td><span>Options defining the behavior of web component or its underlying search functionality.</span></td></tr><tr><td><strong>theme</strong>&nbsp;<span><a href="/mapbox-search-js/api/web/theming/#theme">Theme</a></span>&nbsp;</td><td><span>The <a href="/mapbox-search-js/api/web/theming/#theme">Theme</a> to use for styling the geocoder.<p><code>theme.cssText</code> selectors may target the input bar (<code>.Geocoder</code>, <code>.SearchIcon</code>, <code>.Input</code>, <code>.ActionIcon</code>, <code>.ClearBtn</code>, <code>.LoadingIcon</code>) or the suggestions dropdown (<code>.MapboxSearch</code>, <code>.Label</code>, <code>.Results</code>, <code>.ResultsList</code>, <code>.ResultsAttribution</code>, <code>.Suggestion</code>, <code>.SuggestionIcon</code>, <code>.SuggestionText</code>, <code>.SuggestionName</code>, <code>.SuggestionDesc</code>).</p></span></td></tr><tr><td><strong>popoverOptions</strong>&nbsp;<span>Partial&lt;<a href="#popoveroptions">PopoverOptions</a>&gt;</span>&nbsp;</td><td><span>The <a href="#popoveroptions">PopoverOptions</a> to define popover positioning.</span></td></tr><tr><td><strong>placeholder</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>The input element's placeholder text. The default value may be localized if <a href="#geocodingoptions#language">GeocodingOptions#language</a> is set.</span></td></tr><tr><td><strong>map</strong>&nbsp;<span><a href="#mapinstance">MapInstance</a></span>&nbsp;</td><td><span>If specified, the map will be centered on the retrieved suggestion.</span></td></tr><tr><td><strong>marker</strong>&nbsp;<span>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a> | mapboxgl.MarkerOptions)</span>&nbsp;</td><td><span>If <code>true</code> , a <a href="https://docs.mapbox.com/mapbox-gl-js/api/#marker">Marker</a> 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 <code>false</code> , no marker will be added to the map. Requires that <a href="#geocoderprops#mapboxgl">GeocoderProps#mapboxgl</a> also be set.</span></td></tr><tr><td><strong>mapboxgl</strong>&nbsp;<span>any</span>&nbsp;</td><td><span>A <a href="https://github.com/mapbox/mapbox-gl-js">mapbox-gl</a> instance to use when creating <a href="https://docs.mapbox.com/mapbox-gl-js/api/#marker">Markers</a> . Required if <a href="#geocoderprops#marker">GeocoderProps#marker</a> is <code>true</code> .</span></td></tr><tr><td><strong>value</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>Value to display in the geocoder.</span></td></tr><tr><td><strong>onChange</strong>&nbsp;<span>function (value: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>): void</span>&nbsp;</td><td><span>Callback for when the value changes.</span></td></tr><tr><td><strong>onSuggest</strong>&nbsp;<span>function (res: <a href="#geocodingresponse">GeocodingResponse</a>): void</span>&nbsp;</td><td><span>Fired when the user is typing in the input and provides a list of suggestions. The underlying response from <a href="/mapbox-search-js/api/core/geocoding/#geocodingcore">GeocodingCore</a> is passed.</span></td></tr><tr><td><strong>onSuggestError</strong>&nbsp;<span>function (error: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error">Error</a>): void</span>&nbsp;</td><td><span>Fired when <a href="/mapbox-search-js/api/core/geocoding/#geocodingcore">GeocodingCore</a> has errored providing a list of suggestions. The underlying error is passed.</span></td></tr><tr><td><strong>onRetrieve</strong>&nbsp;<span>function (res: <a href="#geocodingfeature">GeocodingFeature</a>): void</span>&nbsp;</td><td><span>Fired when the user has selected a suggestion. The underlying feature from <a href="/mapbox-search-js/api/core/geocoding/#geocodingcore">GeocodingCore</a> is passed.</span></td></tr><tr><td><strong>onClear</strong>&nbsp;<span>function (): void</span>&nbsp;</td><td><span>Fired when the user has cleared the search box.</span></td></tr><tr><td><strong>onBlur</strong>&nbsp;<span>function (): void</span>&nbsp;</td><td><span>Fired when the user has blurred the search box.</span></td></tr><tr><td><strong>interceptSearch</strong>&nbsp;<span>function (value: <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>): <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>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 <code>null</code> , <code>undefined</code> or empty string is returned, no search request will be performed.</span></td></tr></tbody></table>

#### Import[​](#import)

```javascript
import { Geocoder } from '@mapbox/search-js-react'
```

#### Example

```js
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?[Yes](null)[No](null)

## Hooks

### useGeocodingCore

A React hook that returns a [GeocodingCore](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/geocoding/#geocodingcore) instance.

#### Parameters

| Name | Description |
| --- | --- |
| **options** [GeocodingOptions](#geocodingoptions)  |  |
| **options.accessToken** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | Your Mapbox access token. |

#### Returns

[GeocodingCore](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/geocoding/#geocodingcore)

#### Import[​](#import)

```javascript
import { useGeocodingCore } from '@mapbox/search-js-react'
```

#### Example

```js
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: '...' };
```

#### Related

-   [GeocodingCore](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/geocoding/#geocodingcore)

Was this section on useGeocodingCore helpful?[Yes](null)[No](null)

## Types

### GeocoderRefType

Methods available on a `ref` when attached to the [Geocoder](#geocoder) component.

#### Type

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)

#### Properties

| Name | Description |
| --- | --- |
| **focus** any  |  |
| **search** any  |  |

Was this section on GeocoderRefType helpful?[Yes](null)[No](null)

### GeocodingOptions

Options object for configuring [GeocodingCore](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/geocoding/#geocodingcore), mapped to [Geocoding API](https://docs.mapbox.com/api/search/geocoding/) parameters.

#### Type

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)

#### Properties

<table class="table table--fixed table--compact" style="width:100%;table-layout:fixed"><colgroup><col width="28%"><col></colgroup><thead><tr class="bg-gray-faint"><th style="border-top-left-radius:4px">Name</th><th style="border-top-right-radius:4px">Description</th></tr></thead><tbody><tr><td><strong>autocomplete</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></span>&nbsp;</td><td><span>When autocomplete is enabled, results will be included that start with the requested string, rather than just responses that match it exactly.<p>Defaults to true.</p></span></td></tr><tr><td><strong>bbox</strong>&nbsp;<span>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a> | <a href="#lnglatboundslike">LngLatBoundsLike</a>)</span>&nbsp;</td><td><span>Limit results to only those contained within the supplied bounding box.</span></td></tr><tr><td><strong>country</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>Limit results to one or more countries. Permitted values are <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">ISO 3166 alpha 2</a> country codes separated by commas.</span></td></tr><tr><td><strong>language</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>An <a href="https://en.wikipedia.org/wiki/IETF_language_tag">IETF language tag</a> that controls the language of the text supplied in responses, and also affects result scoring.</span></td></tr><tr><td><strong>limit</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a></span>&nbsp;</td><td><span>The number of results to return, up to <code>10</code> .<p>Defaults to 5.</p></span></td></tr><tr><td><strong>permanent</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></span>&nbsp;</td><td><span>Permanent geocodes are used for use cases that require storing data indefinitely. If 'true', requests will be made with permanent enabled. Separate billing for permanent geocoding will apply.<p>If undefined or 'false', the geocoder will default to use temporary geocoding. Temporary geocoding results are not allowed to be cached.</p><p>For questions related to permanent resource usage and billing, contact <a href="https://www.mapbox.com/contact/sales/">Mapbox sales</a>.</p></span></td></tr><tr><td><strong>proximity</strong>&nbsp;<span>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a> | <a href="#lnglatlike">LngLatLike</a>)</span>&nbsp;</td><td><span>Bias the response to favor results that are closer to this location.<p>Provided as two comma-separated coordinates in longitude,latitude order, or the string <code>ip</code> to bias based on reverse IP lookup.</p></span></td></tr><tr><td><strong>types</strong>&nbsp;<span>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a> | <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Set">Set</a>&lt;<a href="#featuretypes">FeatureTypes</a>&gt;)</span>&nbsp;</td><td><span>Filter results to include only a subset (one or more) of the available feature types. Multiple options can be comma-separated.</span></td></tr><tr><td><strong>worldview</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>Available worldviews are: <code>cn</code> , <code>in</code> , <code>jp</code> , <code>us</code> . If a worldview is not set, <code>us</code> worldview boundaries will be returned.</span></td></tr></tbody></table>

Was this section on GeocodingOptions helpful?[Yes](null)[No](null)

### GeocodingResponse

A `GeocodingResponse` object represents a returned data object from the [Mapbox Geocoding API](https://docs.mapbox.com/api/search/geocoding-v6/#geocoding-response-object).

#### Type

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)

#### Properties

| Name | Description |
| --- | --- |
| **attribution** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | Attributes the results of the Mapbox Geocoding API to Mapbox. |
| **features** [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[GeocodingFeature](#geocodingfeature)>  | The returned feature objects. |
| **type** `"FeatureCollection"`  | `"FeatureCollection"` , a GeoJSON type from the [GeoJSON specification](https://tools.ietf.org/html/rfc7946) . |

Was this section on GeocodingResponse helpful?[Yes](null)[No](null)

### GeocodingFeature

A `GeocodingFeature` object represents a [GeoJSON](https://docs.mapbox.com/help/glossary/geojson/) feature result from the [Mapbox Geocoding API](https://docs.mapbox.com/api/search/geocoding-v6/).

**Legal terms:**

Due to legal terms from our data sources, results from the [Mapbox Geocoding API](https://docs.mapbox.com/api/search/geocoding-v6/) should use the `permanent=true` flag if the results are to be cached/stored in a customer database. Otherwise, results should be used ephemerally and not persisted.

This permanent policy is consistent with the [Mapbox Terms of Service](https://www.mapbox.com/tos/) and failure to comply may result in modified or discontinued service.

Additionally, the [Mapbox Terms of Service](https://www.mapbox.com/tos/) 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

#### Static Members

##### id

Feature id. This property is named "id" to conform to the GeoJSON specification, but is the same id referred to as mapbox_id within the properties object.

###### Type

[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)

#### Related

-   [Geocoding response object](https://docs.mapbox.com/api/search/geocoding-v6/#geocoding-response-object)

Was this section on GeocodingFeature helpful?[Yes](null)[No](null)

### MapboxGeocoderComponentOptions

Options to configure component-specific Search behavior

#### Type

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)

#### Properties

| Name | Description |
| --- | --- |
| **customSearch** function (text: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)): [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[GeocodingFeature](#geocodingfeature)>>  | A function accepting the query string which performs supplemental search results on top of those from the Mapbox Geocoding API. Expected to return a Promise which resolves to an array of GeoJSON-like Features as described in the [Mapbox Geocoding API](https://docs.mapbox.com/api/search/geocoding/#geocoding-response-object) . |
| **flipCoordinates** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)  | If true, the coordinates in the query string are expected to be (lat,lng) instead of (lng,lat). |
| **flyTo** (mapboxgl.FlyToOptions \| [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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 MapboxGeocoderComponentOptions helpful?[Yes](null)[No](null)

### PopoverOptions

Options controlling the display of the Popover used in [AddressAutofill](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/react/autofill/#addressautofill), [MapboxSearchBox](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/web/search/#mapboxsearchbox), and [MapboxGeocoder](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/web/geocoding/#mapboxgeocoder).

#### Type

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)

#### Properties

| Name | Description |
| --- | --- |
| **flip** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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?[Yes](null)[No](null)

### LngLatLike

A [LngLat](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/geography/#lnglat) object, an array of two numbers representing longitude and latitude, or an object with `lng` and `lat` or `lon` and `lat` properties.

#### Type

([LngLat](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/geography/#lnglat) \| [[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number), [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)] \| {lng: [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number), lat: [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)} \| {lon: [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number), lat: [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)})

#### Example

```js
const v1 = new LngLat(-122.420679, 37.772537);
const v2 = [-122.420679, 37.772537];
const v3 = {lon: -122.420679, lat: 37.772537};
```

Was this section on LngLatLike helpful?[Yes](null)[No](null)

### LngLatBoundsLike

A [LngLatBounds](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/geography/#lnglatbounds) object, an array of [LngLatLike](#lnglatlike) objects in [sw, ne] order, or an array of numbers in [west, south, east, north] order.

#### Type

([LngLatBounds](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/geography/#lnglatbounds) \| [[LngLatLike](#lnglatlike), [LngLatLike](#lnglatlike)] \| [[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number), [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number), [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number), [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)])

#### Example

```js
const v1 = new LngLatBounds(
  new LngLat(-73.9876, 40.7661),
  new LngLat(-73.9397, 40.8002)
);
const v2 = new LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
const v3 = [[-73.9876, 40.7661], [-73.9397, 40.8002]];
```

Was this section on LngLatBoundsLike helpful?[Yes](null)[No](null)

### FeatureTypes

Geographic feature data types for the [Mapbox Geocoding API](https://docs.mapbox.com/api/search/geocoding-v6/).

#### Type

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

#### Related

-   [https://docs.mapbox.com/api/search/geocoding-v6/#geographic-feature-types](https://docs.mapbox.com/api/search/geocoding-v6/#geographic-feature-types)

Was this section on FeatureTypes helpful?[Yes](null)[No](null)