Gestures and Events | Mapbox GL JS

This guide explains how to work with user gestures and events in Mapbox GL JS. You'll learn about default map gestures, how to enable and disable gestures, how to listen for user interactions on the map and how to control the map from external events.

Default Map Gestures

Mapbox GL JS provides intuitive gestures to interact with the map. Gestures vary between desktop and mobile devices.

Desktop Gestures

Pan around: Click and drag with mouse.
Adjust pitch: Right-click + drag up/down.
Gradually zoom: Scroll mouse wheel or use touch pinch gesture.
Rotate: Right-click + drag left/right. (Hold control + click + drag left/right on Mac)
Zoom in one level: Double-click.
Zoom out one level: Hold Shift and double-click.
Quick zoom: Hold Shift + drag a box.

Mobile Gestures

Pan around: Tap and drag with touch screen.
Adjust pitch: Two-finger drag up/down.
Gradually zoom: Touch pinch gesture.
Rotate: Two-finger rotate.
Zoom in one level: Double-tap.
Zoom out one level: Two-finger tap.

Enable and Disable Default Gestures

You can enable or disable specific gestures when instantiating a map using the dragPan, scrollZoom, boxZoom, dragRotate, keyboard, and touchZoomRotate options.

Example:


const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v11',
    center: [0, 0],
    zoom: 2,
    dragPan: true, // Enable or disable drag panning
    scrollZoom: false, // Disable scroll zoom
    boxZoom: true, // Enable box zoom
    dragRotate: true, // Enable drag rotation
    keyboard: true, // Enable keyboard controls
    touchZoomRotate: true // Enable touch zoom & rotation
});

You can also enable and disable interactions after the map has been created:


map.scrollZoom.disable();  // Disable scroll zoom
map.scrollZoom.enable();   // Enable scroll zoom

EXAMPLE

Disable map rotation

See an example of a map with rotation disabled.

EXAMPLE

Disable scroll zoom

See an example of a map with scroll zoom disabled.

EXAMPLE

Display a non-interactive map

See an example of a map with all default gestures disabled.

User Interaction Events

You can listen for user interactions on the map object by using events. Some common event types include:

Event Name	Description
`move`	Fires continuously as the map is panned or zoomed
`moveend`	Fires when a panning movement has completed
`zoom`	Fires continuously while the map is zooming
`zoomend`	Fires when zooming has completed
`rotate`	Fires continuously while the map is rotating
`rotateend`	Fires when rotation has completed
`pitch`	Fires continuously when the pitch is changing
`click`	Fires when the user clicks the map

These listeners are used with the on method:


map.on('move', () => {
    console.log('Map is moving');
});

map.on('click', (e) => {
    console.log(`Clicked at: ${e.lngLat.lng}, ${e.lngLat.lat}`);
});

They can also be used with the Interactions API to handle interactions on layers, featuresets, or the map itself.


map.addInteraction('my-polygon-click-interaction', {
  type: 'click',
  target: 'polygons',
  handler: (e) => {
    map.setFeatureState(e.feature, {highlight: true});
  }
});

map.addInteraction('building-mouseenter', {
  type: 'mouseenter',
  target: {featuresetId: 'buildings', importId: 'basemap'},
  handler: (e) => {
    map.setFeatureState(e.feature, {highlight: true});
  }
});

Explore all available events in the API reference documentation.

EXAMPLE

Add feature-level interactions to a map

See an example of a map with interactions on a specific layer.

EXAMPLE

Add interactions to a Mapbox Standard Style

See an example of a map with interactions on a featureset of the Mapbox Standard Style.

External Interactions

You can also control the map using external UI elements like buttons or sliders. Use the map object's methods to programmatically control the map.

Zoom Control

You can build your own zoom in/out UI and use the zoomIn and zoomOut methods to control the map.



const zoomInButton = document.getElementById('zoom-in');

zoomInButton.addEventListener('click', () => {
    map.zoomIn();
});

Fly the Camera

Use the flyTo method to smoothly transition the map to a new location when the user clicks a reset button.


 const zoomOutButton = document.getElementById('reset-map-view');
zoomOutButton.addEventListener('click', () => {
    map.flyTo({
        center: [0, 0],
        zoom: 2
    });
});

EXAMPLE

Fly to a location

See an example of a map with a button that triggers a fly-to animation.

Show or Hide a Layer

Show or hide a layer in the map's style when the user clicks a checkbox.



const checkbox = document.getElementById('toggle-layer');
checkbox.addEventListener('change', (event) => {
    const layerId = 'my-layer';
    if (event.target.checked) {
        map.setLayoutProperty(layerId, 'visibility', 'visible');
    } else {
        map.setLayoutProperty(layerId, 'visibility', 'none');
    }
});