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

# Search Box

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

## Components

### SearchBox

`<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](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="#searchboxoptions">SearchBoxOptions</a>&gt;</span>&nbsp;</td><td><span>Options to pass to the underlying <a href="/mapbox-search-js/api/core/search/#searchboxcore">SearchBoxCore</a> interface.</span></td></tr><tr><td><strong>componentOptions</strong>&nbsp;<span>Partial&lt;<a href="#mapboxsearchboxcomponentoptions">MapboxSearchBoxComponentOptions</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 search box.<p><code>theme.cssText</code> selectors may target the input bar (<code>.SearchBox</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="#searchboxoptions#language">SearchBoxOptions#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="#searchboxprops#mapboxgl">SearchBoxProps#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="#searchboxprops#marker">SearchBoxProps#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 search box.</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="#searchboxsuggestionresponse">SearchBoxSuggestionResponse</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/search/#searchboxcore">SearchBoxCore</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/search/#searchboxcore">SearchBoxCore</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="#searchboxretrieveresponse">SearchBoxRetrieveResponse</a>): void</span>&nbsp;</td><td><span>Fired when the user has selected a suggestion. The underlying response from <a href="/mapbox-search-js/api/core/search/#searchboxcore">SearchBoxCore</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 { SearchBox } from '@mapbox/search-js-react'
```

#### Example

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

## Hooks

### useSearchBoxCore

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

#### Parameters

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

#### Returns

[SearchBoxCore](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/search/#searchboxcore)

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

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

#### Example

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

#### Related

-   [SearchBoxCore](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/search/#searchboxcore)

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

### useSearchSession

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

#### Parameters

| Name | Description |
| --- | --- |
| **search** ([SearchBoxCore](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/search/#searchboxcore) \| [AddressAutofillCore](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/autofill/#addressautofillcore))  |  |

#### Returns

[SearchSession](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/search_session/#searchsession):

#### Related

-   [SearchSession](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/search_session/#searchsession)

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

## Types

### SearchBoxRefType

Methods available on a `ref` when attached to the [SearchBox](#searchbox) 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 SearchBoxRefType helpful?[Yes](null)[No](null)

### SearchBoxOptions

Options object for configuring [SearchBoxCore](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/search/#searchboxcore), mapped to [Search Box API](https://docs.mapbox.com/api/search/search-box/) 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>bbox</strong>&nbsp;<span>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a> | <a href="/mapbox-search-js/api/core/geography/#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>An <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">ISO 3166 alpha-2 country code</a> to be returned.<p>If not specified, results will not be filtered by country.</p></span></td></tr><tr><td><strong>eta_type</strong>&nbsp;<span><code>"navigation"</code></span>&nbsp;</td><td><span>Used to estimate the time of arrival from the location specified in <a href="#searchboxoptions#origin">SearchBoxOptions#origin</a> .<p>The only allowed value for this parameter is navigation. This parameter, along with <a href="#searchboxoptions#origin">SearchBoxOptions#origin</a> and <a href="#searchboxoptions#navigation_profile">SearchBoxOptions#navigation_profile</a>, is required for ETA calculations.</p><p>ETA calculations will incur additional latency.</p></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>The <a href="https://en.wikipedia.org/wiki/IETF_language_tag">IETF language tag</a> to be returned.<p>If not specified, <code>en</code> will be used.</p></span></td></tr><tr><td><strong>limit</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/Number">number</a>)</span>&nbsp;</td><td><span>The number of results to return, up to <code>10</code> .</span></td></tr><tr><td><strong>navigation_profile</strong>&nbsp;<span>(<code>"driving"</code> | <code>"walking"</code> | <code>"cycling"</code>)</span>&nbsp;</td><td><span>The navigation routing profile to use for distance/eta calculations.<p>For distance calculations, both <a href="#searchboxoptions#navigation_profile">SearchBoxOptions#navigation_profile</a> and <a href="#searchboxoptions#origin">SearchBoxOptions#origin</a> must be specified.</p><p>For ETA calculations: <a href="#searchboxoptions#navigation_profile">SearchBoxOptions#navigation_profile</a>, <a href="#searchboxoptions#origin">SearchBoxOptions#origin</a>, and <a href="#searchboxoptions#eta_type">SearchBoxOptions#eta_type</a> must be specified.</p></span></td></tr><tr><td><strong>origin</strong>&nbsp;<span>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a> | <a href="/mapbox-search-js/api/core/geography/#lnglatlike">LngLatLike</a>)</span>&nbsp;</td><td><span>The location from which to calculate distance. <strong>This parameter may incur additional latency.</strong><p>When both <a href="#searchboxoptions#proximity">SearchBoxOptions#proximity</a> and <a href="#searchboxoptions#origin">SearchBoxOptions#origin</a> are specified, <code>origin</code> is interpreted as the target of a route, while <code>proximity</code> indicates the current user location.</p><p>For distance calculations, both <a href="#searchboxoptions#navigation_profile">SearchBoxOptions#navigation_profile</a> and <a href="#searchboxoptions#origin">SearchBoxOptions#origin</a> must be specified.</p><p>For ETA calculations: <a href="#searchboxoptions#navigation_profile">SearchBoxOptions#navigation_profile</a>, <a href="#searchboxoptions#origin">SearchBoxOptions#origin</a>, and <a href="#searchboxoptions#eta_type">SearchBoxOptions#eta_type</a> must be specified.</p></span></td></tr><tr><td><strong>poi_category</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 those that belong to one or more categories, provided as a comma-separated list.</span></td></tr><tr><td><strong>poi_category_exclusions</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>A comma-separated list of canonical category names that limits POI results to those that are not part of the given categories.</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="/mapbox-search-js/api/core/geography/#lnglatlike">LngLatLike</a>)</span>&nbsp;</td><td><span>Bias the response to favor results that are closer to this location.<p>When both <a href="#searchboxoptions#proximity">SearchBoxOptions#proximity</a> and <a href="#searchboxoptions#origin">SearchBoxOptions#origin</a> are specified, <code>origin</code> is interpreted as the target of a route, while <code>proximity</code> indicates the current user location.</p></span></td></tr><tr><td><strong>rich_metadata_provider</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>A comma-separated list of rich metadata providers to include in a suggestion result.</span></td></tr><tr><td><strong>route</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>A polyline encoded linestring describing the route to be used for searching.<p>Both polyline5 and polyline6 precision are accepted, but must be specified using the <a href="#searchboxoptions#route_geometry">SearchBoxOptions#route_geometry</a> parameter.</p></span></td></tr><tr><td><strong>route_geometry</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>Passed in conjunction with a route polyline describing its precision. Options are polyline or polyline6. If this parameter is not provided with a <a href="#searchboxoptions#route">SearchBoxOptions#route</a> , the default is polyline.<p>Accurate results depend on including the correct route_geometry for the <a href="#searchboxoptions#route">SearchBoxOptions#route</a> provided.</p></span></td></tr><tr><td><strong>sar_type</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>This indicates that the user intends to perform a higher cost search-along-route request.<p>This should be included when <a href="#searchboxoptions#route">SearchBoxOptions#route</a> is included and should have a value of isochrone.</p></span></td></tr><tr><td><strong>time_deviation</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/Number">number</a>)</span>&nbsp;</td><td><span>Maximum detour in estimated minutes from route.</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="#searchboxadministrativeunittypes">SearchBoxAdministrativeUnitTypes</a>&gt;)</span>&nbsp;</td><td><span>Limit results to one or more types of features. If no types are specified, all possible types may be returned.<p>Reference: <a href="https://docs.mapbox.com/api/search/search-box/#administrative-unit-types">https://docs.mapbox.com/api/search/search-box/#administrative-unit-types</a></p></span></td></tr></tbody></table>

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

### SearchBoxSuggestionResponse

A `SearchBoxSuggestionResponse` object represents a returned data object from the `suggest` endpoint of the [Mapbox Search Box API](https://docs.mapbox.com/api/search/search-box/#response-get-suggested-results).

#### 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)  | The attribution data for results. |
| **suggestions** [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[SearchBoxSuggestion](#searchboxsuggestion)>  | The returned suggestion objects. |

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

### SearchBoxRetrieveResponse

A `SearchBoxRetrieveResponse` object represents a returned data object from the `/retrieve` endpoint of the [Mapbox Search Box API](https://docs.mapbox.com/api/search/search-box/#response-retrieve-a-suggested-feature).

#### 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)  | The attribution data for results. |
| **features** [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[SearchBoxFeatureSuggestion](#searchboxfeaturesuggestion)>  | The returned feature objects. |

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

### SearchBoxSuggestion

A `SearchBoxSuggestion` object represents a suggestion result from the [Mapbox Search Box API](https://docs.mapbox.com/api/search/search-box/).

SearchBoxSuggestion objects are "part one" of the two-step interactive search experience, and include useful information about the result, such as: [SearchBoxSuggestion#name](#searchboxsuggestion#name), [SearchBoxSuggestion#full_address](#searchboxsuggestion#full_address), and [SearchBoxSuggestion#maki](#searchboxsuggestion#maki).

SearchBoxSuggestion objects do not include geographic coordinates. To get the coordinates of the result, use [SearchBoxCore#retrieve](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/search/#searchboxcore#retrieve).

For tracking purposes, it is useful for any follow-up requests based on this suggestion to include same [SessionToken](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/search_session/#sessiontoken) as the original request.

Reference: [https://docs.mapbox.com/api/search/search-box/#response-get-suggested-results](https://docs.mapbox.com/api/search/search-box/#response-get-suggested-results)

#### Type

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

#### Properties

| Name | Description |
| --- | --- |
| **added_distance** [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)  | The distance added to an input route by including the given suggestion, in meters. |
| **added_time** [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)  | The estimated time added to an input route by including the given suggestion, in minutes. |
| **address** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The address of the result containing the address number and street. |
| **brand** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The brand name of the result, if it is a POI and is applicable. |
| **brand_id** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The canonical brand ID of the result, if it is a POI and is applicable. |
| **context** [SuggestionJSONContext](#suggestionjsoncontext)  | The context of the feature. This context has layers that follow the [Administrative unit types](https://docs.mapbox.com/api/search/search-box/#administrative-unit-types) . |
| **distance** [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)  | An approximate distance to the `origin` location, in meters. Only provided when `origin` and `navigation_profile` are used in the request. |
| **eta** [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)  | The estimated time of arrival from the origin point to the feature, in minutes. Only provided when `eta_type` , `origin` , and `navigation_profile` are used in the request. If an address is not on the road network, an ETA will not be provided. |
| **external_ids** any  | An object containing the IDs of the feature found in external databases, with the keys being the data source names and the values being the IDs. |
| **feature_type** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The type of the result. For POIs, this will be `poi` . For categories, this will be `category` . For address-type results, the global context hierarchy is used ( `country` , `region` , `postcode` , `district` , `place` , `locality` , `neighborhood` , `address` ). See the [Administrative unit types section](https://docs.mapbox.com/api/search/search-box/#administrative-unit-types) for details about these types. |
| **full_address** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The full address of the result, which concatenates [SearchBoxSuggestion#address](#searchboxsuggestion#address) and [SearchBoxSuggestion#place_formatted](#searchboxsuggestion#place_formatted) . |
| **language** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | An IETF language tag indicating the language of the result. |
| **maki** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | A string representing an associated [Maki icon](https://docs.mapbox.com/help/glossary/maki/) to use for this result. |
| **mapbox_id** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The id to use with [SearchBoxCore#retrieve](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/search/#searchboxcore#retrieve) to obtain full feature details. |
| **metadata** any  | An object containing additional metadata for the feature, if applicable. |
| **name** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The name of the feature. |
| **name_preferred** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The preferred name of the feature, if different than [SearchBoxSuggestion#name](#searchboxsuggestion#name) . |
| **place_formatted** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | A formatted string of result context comprised of the place, region, country, and postcode. |
| **poi_category** [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>  | An array including the POI categories the result falls into, if it is a POI. |

#### Example

```js
const search = new SearchBoxCore({ accessToken: 'pk.my-mapbox-access-token' });

const sessionToken = new SessionToken();
const result = await search.suggest('Washington D.C.', { sessionToken });
if (result.suggestions.length === 0) return;

const suggestion = result.suggestions[0];

const { features } = await search.retrieve(suggestion, { sessionToken });
doSomethingWithCoordinates(features);
```

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

### SuggestionJSONContext

Raw JSON form of a suggestion result's "context" from the [Mapbox Search Box API](https://docs.mapbox.com/api/search/search-box/).

Reference: [https://docs.mapbox.com/api/search/search-box/#response-get-suggested-results](https://docs.mapbox.com/api/search/search-box/#response-get-suggested-results)

#### Type

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

#### Properties

| Name | Description |
| --- | --- |
| **address** ContextEntry  | The address of the result including the address number and street |
| **address_number** ContextEntry  | The address number of the result |
| **country** any  | The country of the result |
| **district** ContextEntry  | The district of the result |
| **locality** ContextEntry  | The locality of the result |
| **neighborhood** ContextEntry  | The neighborhood of the result |
| **place** ContextEntry  | The place of the result |
| **postcode** ContextEntry  | The postcode of the result |
| **region** any  | The region of the result |
| **street** ContextEntry  | The street of the result |

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

### SearchBoxFeatureSuggestion

A `SearchBoxFeatureSuggestion` object represents a [GeoJSON](https://docs.mapbox.com/help/glossary/geojson/) suggestion result from the [Mapbox Search Box API](https://docs.mapbox.com/api/search/search-box/).

Feature suggestions are "part two" of the two-step interactive search experience and includes geographic coordinates. Multiple feature suggestions may be returned from a single search query, for example in an airport with multiple terminals.

As per the [Mapbox Search Box API](https://docs.mapbox.com/api/search/search-box/), this will always be [Point](https://geojson.org/geojson-spec.html#point).

**Legal terms:**

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

#### Example

```js
const featureSuggestion = {
  type: 'Feature',
  geometry: {
    type: 'Point',
    coordinates: [0,0]
  },
  properties: {
    name: 'Washington D.C.',
  }
};
```

#### Related

-   [Response: Retrieve feature](https://docs.mapbox.com/api/search/search-box/#response-retrieve-a-suggested-feature)

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

### SearchBoxAdministrativeUnitTypes

Administrative unit types for the [Mapbox Search Box API](https://docs.mapbox.com/api/search/search-box/).

#### Type

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

#### Related

-   [https://docs.mapbox.com/api/search/search-box/#administrative-unit-types](https://docs.mapbox.com/api/search/search-box/#administrative-unit-types)

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

### MapboxSearchBoxComponentOptions

Options to configure component-specific Search behavior

#### Type

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

#### Properties

| Name | Description |
| --- | --- |
| **allowReverse** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)  | Allow the user to query a coordinate string (e.g. "lng,lat") to get a reverse search result. |
| **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)<[SearchBoxSuggestion](#searchboxsuggestion)>>  | A function accepting the query string which performs supplemental search results on top of those from the Mapbox Search Box API. Expected to return a Promise which resolves to an array of suggestions as described in the [Mapbox Search Box API](https://docs.mapbox.com/api/search/search-box/#response-get-suggested-results) . Additionally, each suggestion must include a `_geometry` property matching the "geometry" object format specified in the [retrieved Feature](https://docs.mapbox.com/api/search/search-box/#response-retrieve-a-suggested-feature) format. |
| **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 MapboxSearchBoxComponentOptions 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)