You're all set!

To start developing, please head over to our developer documentation.

Activate the Google Maps JavaScript API

To get you started we'll guide you through the Google Developers Console to do a few things first:

  1. Create or choose a project
  2. Activate the Google Maps JavaScript API and related services
  3. Create appropriate keys
Continue

Scrolling and Panning Behavior

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 either cooperative or greedy, depending on whether the page is scrollable or not. In more detail: if the option is auto, 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 gestureHandling options apply only if the user is viewing the page on a device that supports a touch interface.
  • Touch events only: The gestureHandling options do not apply to mouse or pen events.
  • Not for signed-in maps: The gestureHandling options do not apply to maps with sign-in enabled.
    Note: The signed-in feature is deprecated, and no longer supported in versions 3.28 and higher of the Google Maps JavaScript API.
  • Not for Street View: The gestureHandling options do not apply to the Street View service.

Send feedback about...

Google Maps JavaScript API
Google Maps JavaScript API
Need help? Visit our support page.