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:

loadFired when the map is initialized once its center and zoom have been set for the first time.
clickFired when the user clicks (or taps) the map.
dblclickFired when the user double-clicks (or double-taps) the map.
mousedownFired when the user pushes the mouse button on the map.
mouseupFired when the user releases the mouse button on the map.
mouseoverFired when the mouse enters the map.
mouseoutFired when the mouse leaves the map.
mousemoveFired while the mouse moves over the map.
resizeFired when the map is resized.
change:boundsFired when the map viewport changes, either after a bounds/center or zoom change.
change:centerFired when the center of the map viewport has changed.
change:zoomFired when the zoom level has changed.
change:unitsFired when the active map units type has changed.
moveFired repeatedly during any movement of the pan, including pan and fly animations.
move:startFired when the map starts changing (e.g. user starts dragging the map).
move:endFired when the center of the map stops changning (e.g. user stopped dragging the map).
zoomFired repeatedly during any change in zoom level, including zoom and fly animations.
zoom:startFired when the map zoom is about to change (e.g. before zoom animation).
zoom:endFired when the map has changed, after any animations.
marker:clickFired when the user clicks (or taps) a marker on the map.
marker:dragFired repeatedly while the user drags a marker.
marker:dragstartFired when the user starts dragging a marker.
marker:dragendFired when the user stops dragging a marker.
shape:clickFired when the user clicks (or taps) a shape on the map.
timeline:playFired when the map timeline begins playback.
timeline:stopFired when the map timeline stops playback.
timeline:changeFired when the current time/date for the map timeline changes.
layer:addFired when a layer is added to the map.
layer:removeFired when a layer is removed from the map.
source:addFired when a data source is added to the map.
source.removeFired when a data source is removed from the map.
source:load:startFired when a map data source has started loading data.
source:load:doneFired 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',;

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 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',;
map.on('marker:click', handleMarkerClick);
// later we decide to remove the listener'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.