Controlling Zoom and Pan

Overview

This tutorial shows you how to customize the way users interact with your map. Learn to control whether your users can zoom and pan the map, and also whether the user's page scrolling actions take priority over the map's zooming and panning.

Demo: Preventing map pan and zoom on page scroll

When a user scrolls a page that contains a map, the scrolling action can unintentionally cause the map to zoom. The demo below allows the page to scroll normally, without affecting the map. Users can zoom the map by clicking the zoom controls. They can also zoom and pan by using two-finger movements on the map for touchscreen devices.

See the code below for this map.

function initMap() {
  var locationRio = {lat: -22.915, lng: -43.197};
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 13,
    center: locationRio,
    gestureHandling: 'cooperative'
  });
  var marker = new google.maps.Marker({
    position: locationRio,
    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>

Try it yourself

You can experiment with this code in JSFiddle by clicking the <> icon in the top-right corner of the code window.

<!DOCTYPE html>
<html>
  <head>
    <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>
      function initMap() {
        var locationRio = {lat: -22.915, lng: -43.197};
        var map = new google.maps.Map(document.getElementById('map'), {
          zoom: 13,
          center: locationRio,
          gestureHandling: 'cooperative'
        });
        var marker = new google.maps.Marker({
          position: locationRio,
          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>

Understand the code

The code above sets up a basic map, which may be similar to how you've created maps when getting started with the Maps JavaScript API. Copy the code above into a new index.html file, and open this file in a browser to load the Maps JavaScript API, and put a map on a web page.

Click YOUR_API_KEY in the code sample, or follow the instructions to get an API key. Replace YOUR_API_KEY with your application's API key.

The code within the first script tags above is the starting point that runs the program by creating an initMap function that initializes the map object. The code also sets a specific latitude, longitude and zoom level.

      function initMap() {
        var locationRio = {lat: -22.915, lng: -43.197};
        var map = new google.maps.Map(document.getElementById('map'), {
          zoom: 13,
          center: locationRio,
          gestureHandling: 'cooperative'
        });

The code above does the following:

Sets the gestureHandling property to cooperative to prevent one-finger movements from panning the map on touchscreen and mobile devices. The map pans only when users use two-finger movements.

Note: The gestureHandling property is set to cooperative by default on pages that are scrollable. This means that the map does not change when the user scrolls the page on touchscreen or mobile applications. Read more about gesture handling below.

Demo: Disabling zoom and pan interactions

The example below disables zoom and pan on the map for desktop, touchscreen, and mobile devices.

Get the code

In your index.html file, replace the JavaScript code for the map variable with the code below.

      function initMap() {
        var locationRio = {lat: -22.915, lng: -43.197};
        var map = new google.maps.Map(document.getElementById('map'), {
          zoom: 13,
          center: locationRio,
          gestureHandling: 'none',
          zoomControl: false
        });

Save and open the index.html file in a web browser to display a map that disables zooming and panning.

Understand the code

The above JavaScript code does the following:

Sets the gestureHandling property to none to disable zooming by pinching the map on touchscreen and mobile devices.
Sets the zoomControl property to false to remove the Zoom control buttons on the map.

Note: You can also disable zoom by setting the minZoom and maxZoom to the same value. This also disables scroll on the map.

Demo: Enabling zoom and pan interaction

The example below demonstrates a map that users can zoom and pan on desktop, touchscreen, and mobile devices using the scroll wheel on a mouse, the zoom controls, a trackpad/mouse, or a touchscreen. This demo does not prevent the map from panning or zooming on page scroll.

Get the code

In your index.html file, replace the JavaScript code for the map variable with the code below.

      function initMap() {
        var locationRio = {lat: -22.915, lng: -43.197};
        var map = new google.maps.Map(document.getElementById('map'), {
          zoom: 13,
          center: locationRio,
          gestureHandling: 'greedy'
        });

Save and open the index.html file in a web browser to display a map that enables zoom and pan interaction.

Understand the code

The code above sets the gestureHandling property to greedy for touchscreen and mobile devices, to allow users to pan the map (up or down, left or right) when the user swipes (drags on) the screen. In other words, both a one-finger swipe and two-finger swipe can cause the map to pan.

Understand the terminology

This section defines terminology that's relevant to this tutorial, and various actions that users perform to interact with a map.

Zoom: The action that changes the scale of the map.

For desktop web apps:

Click the + or - buttons on the Zoom control.
Double click using your mouse or trackpad.
Scroll using your mouse or pinch using your trackpad.

For mobile web apps:

You can also pinch the screen to zoom in and out.
Double-tap the screen to zoom in.

Pan/Drag: The action of dragging a map while keeping it at the same scale. Another common term for the pan action is drag.

For desktop web apps:

Click and hold your mouse or trackpad, then drag the maps by moving your mouse or finger. Release to stop panning.
Use your arrow keys: up for north, right for east, down for south and left for west.

For mobile web apps:

Use two fingers to move the map. Note: You can use one finger to pan/drag the map, if the gestureHandling property is set to greedy.

The Maps JavaScript API fires the following events, among others, when the user pans/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.

Page scroll: The action of moving the displayed web page up, down, or across on a desktop or mobile screen.

For desktop/non-touchscreen devices:

Use your mouse or trackpad to move the scroll bar on the webpage.
Roll the mouse scroll wheel forwards or backwards to scroll the webpage.
Move your fingers up or down on the trackpad to scroll the webpage.
Use the mouse scroll wheel to move the webpage up or down.

For mobile web apps:

Move your finger up or down on the screen on touchscreen devices to scroll the page.

Map controls: Elements on the user interface that allow user interaction with the map, like the zoom buttons or street view pegman. Learn more about controls in the developer guides.

The zoom control: This control displays + and - buttons for changing the zoom level of the map. This control appears by default at the bottom right corner of the map. See the image of the zoom control in this section.

gestureHandling: A setting within the Maps JavaScript API that allows developers to control how the API handles gestures on the map. For mobile web in particular, users may swipe the touchscreen, intending to scroll the page, but change the scale of the map instead. Developers can optimize this user experience by using the gestureHandling option in the MapOptions object. The available values for gestureHandling are below:
- 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. On desktop applications, users can zoom or pan the map by scrolling while pressing a modifier key (the ctrl or ⌘ key).
- none: This option disables panning and pinching on the map for mobile devices, and dragging of the map on desktop devices.
- auto (default): Depending on whether the page is scrollable, the Maps JavaScript API sets the gestureHandling property to either cooperative or greedy as below:
  - Set to cooperative if the page body is bigger than the map window, or if the Maps JavaScript API cannot determine the page size (for example, if it's in an iframe).
  - Set to greedy, if the page body is not bigger than the map window and it's unlikely that the user needs to scroll.
The following restrictions and limitations 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.
  
  Note: An exception to this limitation is when viewing maps that have gestureHandling set to none on desktop devices. The none option disables panning and pinching on the map for mobile devices, and dragging of the map on desktop devices.
- 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 Maps JavaScript API.
- Not for Street View: The gestureHandling options do not apply to the Street View service.