Configure Map Gestures with MapTiler SDK
MapTiler SDKEnable cooperative gesture handling so users must Ctrl+scroll to zoom the embedded map.
maptilersdk.config.apiKey = 'YOUR_MAPTILER_KEY';
const map = new maptilersdk.Map({
container: 'map',
style: maptilersdk.MapStyle.STREETS,
center: [2.3522, 48.8566],
zoom: 12,
cooperativeGestures: true
});How it works
Setting cooperativeGestures: true in the constructor prevents accidental map interaction when scrolling a page. Users must hold Ctrl (or Cmd on Mac) while scrolling to zoom, and use two fingers on touch devices to pan.
An overlay message appears automatically when the user tries to interact without the modifier key. This is the same behavior as Google Maps.
Key APIs
| API | Description | Docs |
|---|---|---|
cooperativeGestures |
Constructor option to require modifier keys | docs.maptiler.com/sdk-js/api/ |
FAQ
Can I customize the overlay message?
The SDK uses a built-in message. To customize it, you can override the CSS for the cooperative gesture overlay element.
Does this affect programmatic zoom?
No. Methods like map.zoomTo() and map.flyTo() work normally regardless of this setting.
Common mistakes
- Enabling cooperative gestures on full-page maps where users expect direct interaction
- Confusing
cooperativeGestureswithscrollZoom: false: cooperative gestures still allow zoom with modifier keys, whilescrollZoom: falsedisables it entirely
Build maps using MapTiler SDK with AI
Generate code like this configure map gestures with maptiler sdk example using the MapTiler SDK skill in your IDE.
Related Examples
- Initialize a Map with MapTiler SDK
- See how to do this in Leaflet, MapLibre GL JS or OpenLayers