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.
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.

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.

Last modified: January 31, 2019