const map = new maplibregl.Map({ container: 'map', style: 'https://api.maptiler.com/maps/streets-v4/style.json?key=YOUR_MAPTILER_KEY', center: [13.405, 52.52], zoom: 11, cooperativeGestures: true }); map.addControl(new maplibregl.NavigationControl());

How it works

Setting cooperativeGestures: true requires users to hold Ctrl (or Cmd on Mac) while scrolling to zoom the map, and to use two fingers to pan on touch devices. This prevents accidental map interactions when scrolling a page with an embedded map.

Without cooperative gestures, any scroll event over the map triggers zoom, which frustrates users trying to scroll past the map on mobile or desktop.

MapLibre displays a built-in overlay message when users try to interact without the required modifier.

Key APIs

API	Description	Docs
`cooperativeGestures`	Require modifier key for scroll zoom	maplibre.org docs
`map.scrollZoom.disable()`	Completely disable scroll zoom	maplibre.org docs
`map.dragPan.disable()`	Disable drag panning	maplibre.org docs

FAQ

What is the difference between cooperativeGestures and disabling scroll zoom?

cooperativeGestures still allows zooming with Ctrl+scroll. Disabling scroll zoom removes it entirely, leaving only pinch-zoom and the zoom buttons.

Can I customize the overlay message?

Not directly through the API. You can override the CSS for .maplibregl-cooperative-gesture-screen to change its appearance.

Common mistakes

Placing a full-viewport map with cooperative gestures: users cannot scroll past it on mobile without two fingers
Forgetting NavigationControl when scroll zoom is restricted: users need an alternative way to zoom

Control Map Interactions in MapLibre GL JS

How it works

Key APIs

FAQ

Common mistakes

Build maps using MapLibre GL JS with AI

Related Examples