Automatically fit the camera to map elements

You can automatically frame markers, polylines, polygons, and 3D routes within a <gmp-map-3d> viewport by setting the autofits-camera HTML attribute or autofitsCamera property on supported child elements. When one or more child elements opt in, the map calculates a camera position that keeps all opted-in elements in view.

Automatic camera fitting is available in the v=beta channel of the Maps JavaScript API. For instructions on loading the beta channel, see Versioning.

Supported elements

The following table lists the child elements of Map3DElement that support autofits-camera (autofitsCamera):

HTML element JavaScript class Library Notes
<gmp-marker-3d>, <gmp-marker-3d-interactive> Marker3DElement, Marker3DInteractiveElement maps3d Frames the marker's position.
<gmp-marker>, <gmp-marker-interactive> MarkerElement, MarkerInteractiveElement maps3d Frames the marker's position.
<gmp-polyline-3d>, <gmp-polyline-3d-interactive> Polyline3DElement, Polyline3DInteractiveElement maps3d Frames all coordinates in the polyline's path.
<gmp-polygon-3d>, <gmp-polygon-3d-interactive> Polygon3DElement, Polygon3DInteractiveElement maps3d Frames all coordinates in the polygon's path.
<gmp-route-3d> Route3DElement routes Waits for the route request to resolve, then frames the route path.

Unsupported elements

Model3DElement, PopoverElement, and FlattenerElement don't support autofitsCamera. To frame those elements, set center and range on <gmp-map-3d> or call flyCameraTo.

Fit the camera on initial load

To frame elements when the map loads, add the autofits-camera attribute to each child element you want inside the initial viewport. You don't need to calculate center or range on <gmp-map-3d>:

<gmp-map-3d
  style="height: 400px; width: 100%;"
  mode="hybrid">
  <gmp-marker-3d
    position="47.6205,-122.3493"
    title="Space Needle"
    autofits-camera>
  </gmp-marker-3d>
  <gmp-marker-3d
    position="47.6097,-122.3425"
    title="Pike Place Market"
    autofits-camera>
  </gmp-marker-3d>
  <gmp-polyline-3d
    path="47.6205,-122.3493,0 47.6097,-122.3425,0"
    stroke-color="#4285F4"
    stroke-width="8"
    altitude-mode="clamp-to-ground"
    autofits-camera>
  </gmp-polyline-3d>
</gmp-map-3d>

<script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&v=beta&libraries=maps3d">
</script>

Replace YOUR_API_KEY with your Google Maps Platform API key.

Fit and animate dynamic updates

When you add an opted-in element after initial load, update its coordinates or route endpoints, or set autofitsCamera to true, the map recalculates the camera to frame all opted-in elements. Removing an element or setting autofitsCamera to false leaves the camera at its position and excludes that element from future updates.

To control whether dynamic updates snap or animate, set autofitsCameraAnimation (autofits-camera-animation) on Map3DElement to an AutofitsCameraAnimation value:

  • AutofitsCameraAnimation.NONE ("none", default): Snaps to the updated position without animation.
  • AutofitsCameraAnimation.FLY_TO ("fly-to"): Flies smoothly to the updated position. The initial map load snaps without animation, and FLY_TO falls back to a snap when the user's operating system requests reduced motion.

To configure autofitsCamera and AutofitsCameraAnimation.FLY_TO programmatically, see the following example:

<div id="map-container" style="height: 400px; width: 100%;"></div>

<script>
  async function initMap() {
    const {
      AutofitsCameraAnimation,
      Map3DElement,
      Marker3DElement,
      MapMode,
    } = await google.maps.importLibrary('maps3d');

    const map = new Map3DElement({
      mode: MapMode.HYBRID,
      autofitsCameraAnimation: AutofitsCameraAnimation.FLY_TO,
    });
    document.getElementById('map-container').append(map);

    const originMarker = new Marker3DElement({
      position: { lat: 37.7955, lng: -122.3937 },
      autofitsCamera: true,
    });
    map.append(originMarker);

    /* Adding a second opted-in marker flies the camera to frame both. */
    const destinationMarker = new Marker3DElement({
      position: { lat: 37.8080, lng: -122.4177 },
      autofitsCamera: true,
    });
    map.append(destinationMarker);
  }
</script>
<script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&v=beta&loading=async&callback=initMap">
</script>

Replace YOUR_API_KEY with your Google Maps Platform API key.

How camera properties and restrictions interact

When at least one child element opts in with autofits-camera, Map3DElement combines your map configuration with the calculated bounds according to the following rules:

  • center and range: Overridden by the calculated framing, which adds 20% range padding and enforces an 80 m minimum range. If no opted-in child elements provide coordinates, the map uses its configured center and range as fallbacks.
  • tilt and heading: Treated as suggested values during framing. When omitted, both default to 0° for a top-down, north-up view.
  • roll and fov: Preserved as configured on Map3DElement.
  • Asynchronous child elements: Before rendering the initial view, Map3DElement waits for opted-in asynchronous children such as <gmp-route-3d> to finish loading route geometry.
  • Map and camera restrictions: Geographic bounds and camera limits (minAltitude, maxAltitude, minTilt, maxTilt, minHeading, and maxHeading) still constrain the autofitted view. For more information, see Restrict camera view and bounds.

Next steps