Controlling Zoom and Pan

Select platform: Android iOS JavaScript

Overview

The usage of a map on a web page may require specific options to control the way users interact with the map to zoom and pan. These options, such as gestureHandling, minZoom, maxZoom and restriction, are defined within the MapOptions interface.

Default Behavior

The following map demonstrates the default behavior for map interactions with a map instantiated with only the zoom and center options defined.

The code for this map is below.

TypeScript

new google.maps.Map(document.getElementById("map")!, {
  zoom,
  center,
});
index.ts

JavaScript

new google.maps.Map(document.getElementById("map"), {
  zoom,
  center,
});
index.js

Controlling Gesture Handling

When a user scrolls a page that contains a map, the scrolling action can unintentionally cause the map to zoom. This behavior can be controlled using the gestureHandling map option.

gestureHandling: cooperative

The map below uses the gestureHandling option set to cooperative, allowing the user to scroll the page normally, without zooming or panning 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.

The code for this map is below.

TypeScript

new google.maps.Map(document.getElementById("map")!, {
  zoom,
  center,
  gestureHandling: "cooperative",
});
index.ts

JavaScript

new google.maps.Map(document.getElementById("map"), {
  zoom,
  center,
  gestureHandling: "cooperative",
});
index.js

View Sample

gestureHandling: auto

The map at the top of the page without the gestureHandling option has the same behavior as the preceding map with gestureHandling set to cooperative because all of the maps on this page are within an <iframe>. The default gestureHandling value auto switches between greedy and cooperative based upon whether the map is contained within an <iframe>.

Map contained within <iframe> Behavior
yes cooperative
no greedy

gestureHandling: greedy

A map with gestureHandling set to greedy is below. This map reacts to all touch gestures and scroll events unlike cooperative.

gestureHandling: none

The gestureHandling option can also be set to none to disable gestures on the map.

Disabling Pan and Zoom

To entirely disable the ability to pan and zoom the map, two options, gestureHandling and zoomControl, must be included.

TypeScript

new google.maps.Map(document.getElementById("map")!, {
  zoom,
  center,
  gestureHandling: "none",
  zoomControl: false,
});
index.ts

JavaScript

new google.maps.Map(document.getElementById("map"), {
  zoom,
  center,
  gestureHandling: "none",
  zoomControl: false,
});
index.js

The map below demonstrates the combination of gestureHandling and zoomControl in the code above.

Restricting Map Bounds and Zoom

It may be desireable to allow gestures and zoom controls but restrict the map to a particular bounds or a minimum and maximum zoom. To accomplish this you may set the restriction, minZoom, and maxZoom options. The following code and map demonstrate these options.

TypeScript

new google.maps.Map(document.getElementById("map")!, {
  zoom,
  center,
  minZoom: zoom - 3,
  maxZoom: zoom + 3,
  restriction: {
    latLngBounds: {
      north: -10,
      south: -40,
      east: 160,
      west: 100,
    },
  },
});
index.ts

JavaScript

new google.maps.Map(document.getElementById("map"), {
  zoom,
  center,
  minZoom: zoom - 3,
  maxZoom: zoom + 3,
  restriction: {
    latLngBounds: {
      north: -10,
      south: -40,
      east: 160,
      west: 100,
    },
  },
});
index.js