Using the gestureHandling option in the
MapOptions
object, you can control the panning and scrolling behavior of a map when
viewed on a mobile device.
Example
The following example uses cooperative gesture handling. View
the demo on a mobile device to see the code in action.
/**
* This sample sets the gesture handling mode to 'cooperative',
* which means that on a mobile device, the user must swipe with one
* finger to scroll the page and two fingers to pan the map.
*/
function initMap() {
var myLatLng = {lat: -25.363, lng: 131.044};
var map = new google.maps.Map(document.getElementById('map'), {
zoom: 4,
center: myLatLng,
gestureHandling: 'cooperative'
});
var marker = new google.maps.Marker({
position: myLatLng,
map: map,
title: 'Hello World!'
});
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
* element that contains the map. */
#map {
height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
height: 100%;
margin: 0;
padding: 0;
}
<!-- Replace the value of the key parameter with your own API key. --> <script async defer src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap"> </script>
<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="initial-scale=1.0, user-scalable=no">
<meta charset="utf-8">
<title>Cooperative Gesture Handling</title>
<style>
/* Always set the map height explicitly to define the size of the div
* element that contains the map. */
#map {
height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
height: 100%;
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<div id="map"></div>
<script>
/**
* This sample sets the gesture handling mode to 'cooperative',
* which means that on a mobile device, the user must swipe with one
* finger to scroll the page and two fingers to pan the map.
*/
function initMap() {
var myLatLng = {lat: -25.363, lng: 131.044};
var map = new google.maps.Map(document.getElementById('map'), {
zoom: 4,
center: myLatLng,
gestureHandling: 'cooperative'
});
var marker = new google.maps.Marker({
position: myLatLng,
map: map,
title: 'Hello World!'
});
}
</script>
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>
</body>
</html>
Gesture handling
On the mobile web, it can be annoying for users when they swipe, intending to scroll the page, but the map pans instead.
The Google Maps JavaScript API provides a gestureHandling
option in the
MapOptions
object that you can use to optimize your users' experience
when interacting with the map. The available values are:
greedy: The map always pans (up or down, left or right) when the user swipes (drags on) the screen. In other words, both a one-finger swipe and a two-finger swipe cause the map to pan.cooperative: The user must swipe with one finger to scroll the page and two fingers to pan the map. If the user swipes the map with one finger, an overlay appears on the map, with a prompt telling the user to use two fingers to move the map. View the sample above on a mobile device to see cooperative mode in action.none: The map is not pannable or pinchable.auto(default): The behavior is eithercooperativeorgreedy, depending on whether the page is scrollable or not. In more detail: if the option isauto, the API chooses the following behavior:cooperative, if the page body is bigger than the window or if the API cannot determine the page size (for example, if it's in an iframe).greedy, if the page body is not bigger than the window and it's therefore unlikely that the user needs to scroll.
The fullscreen control is visible by default on mobile devices, so users can easily enlarge the map. When the map is in fullscreen mode, users can pan the map using one or two fingers. Note: iOS doesn't support the fullscreen feature. The fullscreen control is therefore not visible on iOS devices.
Events
The API fires the following events, among others, when the user scrolls (drags) the map:
drag: Repeatedly fired while the user drags the map.dragstart: Fired when the user starts dragging the map.dragend: Fired when the user stops dragging the map.
See the guide to events and the reference for more information.
Restrictions and limitations
The following restrictions apply to the behavior made available in the
gestureHandling option:
- Touch-sensitive devices only: The
gestureHandlingoptions apply only if the user is viewing the page on a device that supports a touch interface. - Touch events only: The
gestureHandlingoptions do not apply to mouse or pen events. - Not for signed-in maps: The
gestureHandlingoptions do not apply to maps with sign-in enabled. - Not for Street View: The
gestureHandlingoptions do not apply to the Street View service.
Need help? Visit our