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

# Events and event types

`Map` and other Mapbox GL JS classes emit events in response to user interactions or changes in state. `Evented` is the interface used to bind and unbind listeners for these events. This page describes the different types of events that Mapbox GL JS can raise.

You can learn more about the originating events here:

-   [`Map` events](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map-events) fire when a user interacts with a `Map`.
-   [`Marker` events](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#marker-events) fire when a user interacts with a `Marker`.
-   [`Popup` events](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#popup-events) fire when a user interacts with a `Popup`.
-   [`GeolocationControl` events](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/markers/#geolocatecontrol-events) fire when a user interacts with a `GeolocationControl`.

## Evented

[Source Code](https://github.com/mapbox/mapbox-gl-js/blob/29a082c40985763b038163d555f9305cb39233ad/src/util/evented.ts#L73-L208)

`Evented` mixes methods into other classes for event capabilities.

Unless you are developing a plugin you will most likely use these methods through classes like `Map` or `Popup`.

For lists of events you can listen for, see API documentation for specific classes: [`Map`](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-events), [`Marker`](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-events), [`Popup`](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-events), and [`GeolocationControl`](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-events).

### Instance Members

#### on()

Adds a listener to a specified event type.

##### Parameters

| Name | Description |
| --- | --- |
| **type** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The event type to add a listen for. |
| **listener** [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)  | The function to be called when the event is fired. The listener function is called with the data object passed to `fire` , extended with `target` and `type` properties. |

##### Returns

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object): Returns itself to allow for method chaining.

#### off()

Removes a previously registered event listener.

##### Parameters

| Name | Description |
| --- | --- |
| **type** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The event type to remove listeners for. |
| **listener** [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)  | The listener function to remove. |

##### Returns

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object): Returns itself to allow for method chaining.

#### once()

Adds a listener that will be called only once to a specified event type.

The listener will be called first time the event fires after the listener is registered.

##### Parameters

| Name | Description |
| --- | --- |
| **type** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The event type to listen for. |
| **listener** [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)  | (Optional) The function to be called when the event is fired once. If not provided, returns a Promise that will be resolved when the event is fired once. |

##### Returns

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object): Returns `this` \| Promise.

## MapBoxZoomEvent

[Source Code](https://github.com/mapbox/mapbox-gl-js/blob/29a082c40985763b038163d555f9305cb39233ad/src/ui/events.ts#L376-L400)

`MapBoxZoomEvent` is a class used to generate the events 'boxzoomstart', 'boxzoomend', and 'boxzoomcancel'. For a full list of available events, see [`Map` events](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map-events).

### Type

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

### Properties

| Name | Description |
| --- | --- |
| **originalEvent** [MouseEvent](https://developer.mozilla.org/docs/Web/API/MouseEvent)  | The DOM event that triggered the boxzoom event. Can be a `MouseEvent` or `KeyboardEvent` . |
| **target** [Map](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map)  | The `Map` instance that triggered the event. |
| **type** (`"boxzoomstart"` \| `"boxzoomend"` \| `"boxzoomcancel"`)  | The type of originating event. For a full list of available events, see [`Map` events](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map-events) . |

### Example

```js
// Example trigger of a BoxZoomEvent of type "boxzoomstart"
map.on('boxzoomstart', (e) => {
    console.log('event type:', e.type);
    // event type: boxzoomstart
});
```

```js
// Example of a BoxZoomEvent of type "boxzoomstart"
// {
//   originalEvent: {...},
//   type: "boxzoomstart",
//   target: {...}
// }
```

### Related

-   [Reference: `Map` events API documentation](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-events)
-   [Example: Highlight features within a bounding box](https://docs.mapbox.com/mapbox-gl-js/example/using-box-queryrenderedfeatures/)

## MapDataEvent

[Source Code](https://github.com/mapbox/mapbox-gl-js/blob/29a082c40985763b038163d555f9305cb39233ad/src/ui/events.ts#L424-L461)

`MapDataEvent` is a type of events related to loading data, styles, and sources. For a full list of available events, see [`Map` events](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map-events).

### Type

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

### Properties

| Name | Description |
| --- | --- |
| **coord** OverscaledTileID?  | The coordinate of the tile if the event has a `dataType` of `source` and the event is related to loading of a tile. |
| **dataType** (`"source"` \| `"style"`)  | The type of data that has changed. One of `'source'` or `'style'` , where `'source'` refers to the data associated with any source, and `'style'` refers to the entire [style](https://docs.mapbox.com/help/glossary/style/) used by the map. |
| **isSourceLoaded** [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?  | True if the event has a `dataType` of `source` and the source has no outstanding network requests. |
| **source** [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?  | The [style spec representation of the source](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/) if the event has a `dataType` of `source` . |
| **sourceDataType** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?  | Included if the event has a `dataType` of `source` and the event signals that internal data has been received or changed. Possible values are `metadata` , `content` and `visibility` , and `error` . |
| **sourceId** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?  | The `id` of the [`source`](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/) that triggered the event, if the event has a `dataType` of `source` . Same as the `id` of the object in the `source` property. |
| **tile** [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?  | The tile being loaded or changed, if the event has a `dataType` of `source` and the event is related to loading of a tile. |
| **type** (`"data"` \| `"dataloading"` \| `"styledata"` \| `"styledataloading"` \| `"sourcedata"` \| `"sourcedataloading"`)  | The type of originating event. For a full list of available events, see [`Map` events](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map-events) . |

### Example

```js
// Example of a MapDataEvent of type "sourcedata"
map.on('sourcedata', (e) => {
    console.log(e);
    // {
    //   dataType: "source",
    //   isSourceLoaded: false,
    //   source: {
    //     type: "vector",
    //     url: "mapbox://mapbox.mapbox-streets-v8,mapbox.mapbox-terrain-v2"
    //   },
    //   sourceDataType: "visibility",
    //   sourceId: "composite",
    //   style: {...},
    //   target: {...},
    //   type: "sourcedata"
    // }
});
```

### Related

-   [Reference: `Map` events API documentation](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-events)
-   [Example: Change a map's style](https://docs.mapbox.com/mapbox-gl-js/example/setstyle/)
-   [Example: Add a GeoJSON line](https://docs.mapbox.com/mapbox-gl-js/example/geojson-line/)

## MapMouseEvent

[Source Code](https://github.com/mapbox/mapbox-gl-js/blob/29a082c40985763b038163d555f9305cb39233ad/src/ui/events.ts#L57-L156)

`MapMouseEvent` is a class used by other classes to generate mouse events of specific types such as 'click' or 'hover'. For a full list of available events, see [`Map` events](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map-events).

Extends [Event](https://developer.mozilla.org/docs/Web/API/Event).

### Example

```js
// Example of a MapMouseEvent of type "click"
map.on('click', (e) => {
    console.log(e);
    // {
    //     lngLat: {
    //         lng: 40.203,
    //         lat: -74.451
    //     },
    //     originalEvent: {...},
    //     point: {
    //         x: 266,
    //         y: 464
    //     },
    //      target: {...},
    //      type: "click"
    // }
});
```

### Instance Members

#### type

The type of originating event. For a full list of available events, see [`Map` events](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map-events).

##### Type

MapMouseEventType

#### target

The `Map` object that fired the event.

##### Type

MapboxMap

#### originalEvent

The DOM event which caused the map event.

##### Type

[MouseEvent](https://developer.mozilla.org/docs/Web/API/MouseEvent)

#### point

The pixel coordinates of the mouse cursor, relative to the map and measured from the top left corner.

##### Type

[Point](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/geography/#point)

#### lngLat

The geographic location on the map of the mouse cursor.

##### Type

[LngLat](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/geography/#lnglat)

#### features

If a single `layerId`(as a single string) or multiple `layerIds` (as an array of strings) were specified when adding the event listener with [Map#on](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map#on), `features` will be an array of [GeoJSON](http://geojson.org/) [Feature objects](https://tools.ietf.org/html/rfc7946#section-3.2). The array will contain all features from that layer that are rendered at the event's point, in the order that they are rendered with the topmost feature being at the start of the array. The `features` are identical to those returned by [Map#queryRenderedFeatures](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map#queryrenderedfeatures).

If no `layerId` was specified when adding the event listener, `features` will be `undefined`. You can get the features at the point with `map.queryRenderedFeatures(e.point)`.

##### Type

[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<GeoJSONFeature>

##### Example

```js
// logging features for a specific layer (with `e.features`)
map.on('click', 'myLayerId', (e) => {
    console.log(`There are ${e.features.length} features at point ${e.point}`);
});
```

```js
// logging features for two layers (with `e.features`)
map.on('click', ['layer1', 'layer2'], (e) => {
    console.log(`There are ${e.features.length} features at point ${e.point}`);
});
```

```js
// logging all features for all layers (without `e.features`)
map.on('click', (e) => {
    const features = map.queryRenderedFeatures(e.point);
    console.log(`There are ${features.length} features at point ${e.point}`);
});
```

#### preventDefault()

Prevents subsequent default processing of the event by the map.

Calling this method will prevent the following default map behaviors:

-   On `mousedown` events, the behavior of [DragPanHandler](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/handlers/#dragpanhandler).
-   On `mousedown` events, the behavior of [DragRotateHandler](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/handlers/#dragrotatehandler).
-   On `mousedown` events, the behavior of [BoxZoomHandler](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/handlers/#boxzoomhandler).
-   On `dblclick` events, the behavior of [DoubleClickZoomHandler](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/handlers/#doubleclickzoomhandler).

##### Example

```js
map.on('click', (e) => {
    e.preventDefault();
});
```

### Related

-   [Reference: `Map` events API documentation](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-events)
-   [Example: Display popup on click](https://docs.mapbox.com/mapbox-gl-js/example/popup-on-click/)
-   [Example: Display popup on hover](https://www.mapbox.com/mapbox-gl-js/example/popup-on-hover/)

## MapTouchEvent

[Source Code](https://github.com/mapbox/mapbox-gl-js/blob/29a082c40985763b038163d555f9305cb39233ad/src/ui/events.ts#L197-L301)

`MapTouchEvent` is a class used by other classes to generate mouse events of specific types such as 'touchstart' or 'touchend'. For a full list of available events, see [`Map` events](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map-events).

Extends [Event](https://developer.mozilla.org/docs/Web/API/Event).

### Example

```js
// Example of a MapTouchEvent of type "touch"
map.on('touchstart', (e) => {
    console.log(e);
    // {
    //   lngLat: {
    //      lng: 40.203,
    //      lat: -74.451
    //   },
    //   lngLats: [
    //      {
    //         lng: 40.203,
    //         lat: -74.451
    //      }
    //   ],
    //   originalEvent: {...},
    //   point: {
    //      x: 266,
    //      y: 464
    //   },
    //   points: [
    //      {
    //         x: 266,
    //         y: 464
    //      }
    //   ]
    //   preventDefault(),
    //   target: {...},
    //   type: "touchstart"
    // }
});
```

### Instance Members

#### type

The type of originating event. For a full list of available events, see [`Map` events](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map-events).

##### Type

MapTouchEventType

#### target

The `Map` object that fired the event.

##### Type

MapboxMap

#### originalEvent

The DOM event which caused the map event.

##### Type

[TouchEvent](https://developer.mozilla.org/docs/Web/API/TouchEvent)

#### lngLat

The geographic location on the map of the center of the touch event points.

##### Type

[LngLat](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/geography/#lnglat)

#### point

The pixel coordinates of the center of the touch event points, relative to the map and measured from the top left corner.

##### Type

[Point](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/geography/#point)

#### points

The array of pixel coordinates corresponding to a [touch event's `touches`](https://developer.mozilla.org/en-US/docs/Web/API/TouchEvent/touches) property.

##### Type

[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Point](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/geography/#point)>

#### lngLats

The geographical locations on the map corresponding to a [touch event's `touches`](https://developer.mozilla.org/en-US/docs/Web/API/TouchEvent/touches) property.

##### Type

[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[LngLat](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/geography/#lnglat)>

#### features

If a `layerId` was specified when adding the event listener with [Map#on](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map#on), `features` will be an array of [GeoJSON](http://geojson.org/) [Feature objects](https://tools.ietf.org/html/rfc7946#section-3.2). The array will contain all features from that layer that are rendered at the event's point. The `features` are identical to those returned by [Map#queryRenderedFeatures](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map#queryrenderedfeatures).

If no `layerId` was specified when adding the event listener, `features` will be `undefined`. You can get the features at the point with `map.queryRenderedFeatures(e.point)`.

##### Type

([Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<GeoJSONFeature> \| [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined))

##### Example

```js
// logging features for a specific layer (with `e.features`)
map.on('touchstart', 'myLayerId', (e) => {
    console.log(`There are ${e.features.length} features at point ${e.point}`);
});
```

```js
// logging all features for all layers (without `e.features`)
map.on('touchstart', (e) => {
    const features = map.queryRenderedFeatures(e.point);
    console.log(`There are ${features.length} features at point ${e.point}`);
});
```

#### preventDefault()

Prevents subsequent default processing of the event by the map.

Calling this method will prevent the following default map behaviors:

-   On `touchstart` events, the behavior of [DragPanHandler](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/handlers/#dragpanhandler).
-   On `touchstart` events, the behavior of [TouchZoomRotateHandler](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/handlers/#touchzoomrotatehandler).

##### Example

```js
map.on('touchstart', (e) => {
    e.preventDefault();
});
```

### Related

-   [Reference: `Map` events API documentation](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-events)
-   [Example: Create a draggable point](https://docs.mapbox.com/mapbox-gl-js/example/drag-a-point/)

## MapWheelEvent

[Source Code](https://github.com/mapbox/mapbox-gl-js/blob/29a082c40985763b038163d555f9305cb39233ad/src/ui/events.ts#L325-L372)

`MapWheelEvent` is a class used by other classes to generate mouse events of specific types such as 'wheel'. For a full list of available events, see [`Map` events](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map-events).

Extends [Event](https://developer.mozilla.org/docs/Web/API/Event).

### Example

```js
// Example event trigger for a MapWheelEvent of type "wheel"
map.on('wheel', (e) => {
    console.log('event type:', e.type);
    // event type: wheel
});
```

```js
// Example of a MapWheelEvent of type "wheel"
// {
//   originalEvent: WheelEvent {...},
// 	 target: Map {...},
// 	 type: "wheel"
// }
```

### Instance Members

#### type

The type of originating event. For a full list of available events, see [`Map` events](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/map/#map-events).

##### Type

MapWheelEventType

#### target

The `Map` object that fired the event.

##### Type

MapboxMap

#### originalEvent

The DOM event which caused the map event.

##### Type

[WheelEvent](https://developer.mozilla.org/docs/Web/API/WheelEvent)

#### preventDefault()

Prevents subsequent default processing of the event by the map. Calling this method will prevent the the behavior of [ScrollZoomHandler](https://docs.mapbox.com/mapbox-gl-js/mapbox-gl-js/api/handlers/#scrollzoomhandler).

##### Example

```js
map.on('wheel', (e) => {
    // Prevent the default map scroll zoom behavior.
    e.preventDefault();
});
```

### Related

-   [Reference: `Map` events API documentation](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-events)