# @mapbox/mapbox-gl-geocoder

> A geocoder control for Mapbox GL JS

Latest version **5.1.2** (published 2025-08-28) · ISC license · 0 weekly downloads

## Install

```sh
npm install @mapbox/mapbox-gl-geocoder
pnpm add @mapbox/mapbox-gl-geocoder
yarn add @mapbox/mapbox-gl-geocoder
bun add @mapbox/mapbox-gl-geocoder
```

## Health

**Score 43/100 (D)** — status: stable.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 5.1.2 |
| Published | 2025-08-28 |
| First published | 2017-01-22 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | separate (@types/mapbox__mapbox-gl-geocoder) |
| Module format | CommonJS |
| Node | >=6 |
| Dependencies | 7 |
| Unpacked size | 158.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 388 |
| Author | Mapbox |
| Maintainers | mapbox-npm-01, mapbox-npm-02, mapbox-npm-07, mapbox-npm-03, mapbox-npm-04, mapbox-npm-09, mapbox-npm-05, mapbox-npm-06, mapbox-npm-08, mapbox-npm-advanced-actions, mapbox-npm-ci, mapbox-npm, mapbox-admin, mapbox-machine-user, mbx-npm-ci-staging, mbx-npm-ci-production, mbx-npm-01-production, mbx-npm-02-production, mbx-npm-03-production, mbx-npm-04-production, mbx-npm-05-production, mbx-npm-06-production, mbx-npm-07-production, mbx-npm-08-production, mbx-npm-09-production, mbx-npm-02-staging, mbx-npm-advanced-actions-staging, mbx-npm-advanced-actions-production |
| Keywords | geocoder, osm, gl |

## Links

- npm: https://www.npmjs.com/package/@mapbox/mapbox-gl-geocoder
- Repository: https://github.com/mapbox/mapbox-gl-geocoder
- Homepage: https://github.com/mapbox/mapbox-gl-geocoder#readme
- Issues: https://github.com/mapbox/mapbox-gl-geocoder/issues
- npm.io page: https://npm.io/package/@mapbox/mapbox-gl-geocoder

## Dependencies (7)

- [xtend](https://npm.io/package/xtend.md) ^4.0.1
- [events](https://npm.io/package/events.md) ^3.3.0
- [nanoid](https://npm.io/package/nanoid.md) ^3.1.31
- [subtag](https://npm.io/package/subtag.md) ^0.5.0
- [suggestions](https://npm.io/package/suggestions.md) ^1.6.0
- [lodash.debounce](https://npm.io/package/lodash.debounce.md) ^4.0.6
- [@mapbox/mapbox-sdk](https://npm.io/package/@mapbox/mapbox-sdk.md) ^0.16.1

## Recent versions

- 5.1.2 (latest) — 2025-08-28
- 5.1.0-beta.0 (beta) — 2023-05-18
- 5.1.1 — 2025-08-27
- 5.1.0 — 2025-07-16
- 5.0.3 — 2024-09-13
- 5.0.2 — 2023-12-15
- 5.0.1 — 2022-05-11
- 5.0.0 — 2022-03-10
- 4.7.4 — 2021-09-15
- 4.7.3 — 2021-08-16
- 4.7.2 — 2021-07-16
- 4.7.1 — 2021-05-25
- 4.7.0 — 2020-08-17
- 4.6.0 — 2020-07-20
- 4.5.1 — 2019-12-18
- … 25 more at https://npm.io/package/@mapbox/mapbox-gl-geocoder/versions

## README

Mapbox GL Geocoder [![Build Status](https://travis-ci.com/mapbox/mapbox-gl-geocoder.svg?branch=master)](https://travis-ci.com/mapbox/mapbox-gl-geocoder)
---

A geocoder control for [mapbox-gl-js](https://github.com/mapbox/mapbox-gl-js) using the [Mapbox Geocoding API](https://docs.mapbox.com/api/search/#geocoding). For a JavaScript geocoder without a graphical user interface see the [Mapbox SDK for JS](https://github.com/mapbox/mapbox-sdk-js/blob/master/docs/services.md#geocoding).

### Usage

* https://docs.mapbox.com/mapbox-gl-js/example/mapbox-gl-geocoder/
* https://docs.mapbox.com/mapbox-gl-js/example/?search=mapbox-gl-geocoder

**If you are supporting older browsers, you will need to use a polyfill.** We recommend working with [@babel/polyfill](https://babeljs.io/docs/en/babel-polyfill).

### Usage with a module bundler

```bash
npm install --save @mapbox/mapbox-gl-geocoder
```

```js
import MapboxGeocoder from '@mapbox/mapbox-gl-geocoder';
import '@mapbox/mapbox-gl-geocoder/dist/mapbox-gl-geocoder.css';
...
const geocoder = new MapboxGeocoder({
    accessToken: mapboxgl.accessToken,
    mapboxgl: mapboxgl
});

```

###  Using without a Map
It is possible to use the plugin without it being placed as a control on a mapbox-gl map. Keep in mind that the Mapbox [Terms of Service](https://www.mapbox.com/legal/tos#[GAGA]) require that POI search results be shown on a Mapbox map. If you don't need POIs, you can exclude them from your search results with the `options.types` parameter  when constructing a new Geocoder. 

### Deeper dive

#### API Documentation

See [API.md](https://github.com/mapbox/mapbox-gl-geocoder/blob/master/API.md) for complete reference.

#### Examples

See [https://docs.mapbox.com/mapbox-gl-js/examples/#geocoder](https://docs.mapbox.com/mapbox-gl-js/examples/#geocoder).

### Contributing

See [CONTRIBUTING.md](https://github.com/mapbox/mapbox-gl-geocoder/blob/master/CONTRIBUTING.md).

---
_Source: https://npm.io/package/@mapbox/mapbox-gl-geocoder · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._