Interactive Map Events

An interactive map instance will trigger numerous events, such as when the visible region changes or layers are added or removed. You can respond to any of these changes by adding your own event handler on your map instance.

The following events are currently triggered by a Map instance:

Event	Description
`load`	Fired when the map is initialized once its center and zoom have been set for the first time.
`click`	Fired when the user clicks (or taps) the map.
`dblclick`	Fired when the user double-clicks (or double-taps) the map.
`mousedown`	Fired when the user pushes the mouse button on the map.
`mouseup`	Fired when the user releases the mouse button on the map.
`mouseover`	Fired when the mouse enters the map.
`mouseout`	Fired when the mouse leaves the map.
`mousemove`	Fired while the mouse moves over the map.
`resize`	Fired when the map is resized.
`change:bounds`	Fired when the map viewport changes, either after a bounds/center or zoom change.
`change:center`	Fired when the center of the map viewport has changed.
`change:zoom`	Fired when the zoom level has changed.
`change:units`	Fired when the active map units type has changed.
`move`	Fired repeatedly during any movement of the pan, including pan and fly animations.
`move:start`	Fired when the map starts changing (e.g. user starts dragging the map).
`move:end`	Fired when the center of the map stops changning (e.g. user stopped dragging the map).
`zoom`	Fired repeatedly during any change in zoom level, including zoom and fly animations.
`zoom:start`	Fired when the map zoom is about to change (e.g. before zoom animation).
`zoom:end`	Fired when the map has changed, after any animations.
`marker:click`	Fired when the user clicks (or taps) a marker on the map.
`marker:drag`	Fired repeatedly while the user drags a marker.
`marker:dragstart`	Fired when the user starts dragging a marker.
`marker:dragend`	Fired when the user stops dragging a marker.
`shape:click`	Fired when the user clicks (or taps) a shape on the map.
`timeline:play`	Fired when the map timeline begins playback.
`timeline:stop`	Fired when the map timeline stops playback.
`timeline:change`	Fired when the current time/date for the map timeline changes.
`layer:add`	Fired when a layer is added to the map.
`layer:remove`	Fired when a layer is removed from the map.
`source:add`	Fired when a data source is added to the map.
`source.remove`	Fired when a data source is removed from the map.
`source:load:start`	Fired when a map data source has started loading data.
`source:load:done`	Fired when a map data source has completed loading data.

Adding Event Listeners

You add event listeners to your map instance using the on() method. This method requires the event name, as a string, and the handler function to call when the event is triggered.

For example, you may want to perform a certain action when a user selects a marker on the map. Just add an event listener for the marker:click event:

map.on('marker:click', (e) => {
    console.log('marker click', e.data);
});

Your event handler function will receive a single argument, which is the Event instance that was triggered by the event. In several cases, this Event object will also contain a data property that is an object with additional data or object references associated with the event.

So in the above event handler for a marker:click event, we are outputting the value of e.data to the console as that is the data that was associated with the event. For this particular event, this object will contain a data property, which is the model data for the marker, and a marker property, which is the map marker instance on the map.

Removing Event Listeners

Similar to adding events, you can remove event listeners from a map instance using the off() method. This method only requires the event name, as a string, and a reference to the original handler function used in on() to be provided.

Suppose we know we will want to remove the event listener at some point in the future. We'd want to store a reference to the event handler so we can remove it later:

// create a reference to the event handler function
const handleMarkerClick = (e) => {
    console.log('marker click', e.data);
}
map.on('marker:click', handleMarkerClick);
 
// later we decide to remove the listener
map.off('marker:click', handleMarkerClick);

If you know you won't need to reference the event handler function later, then you can just provide the handler function as an inline paramter to on() instead.

Configuration Managing Data Sources