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, andFLY_TOfalls 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:
centerandrange: 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 configuredcenterandrangeas fallbacks.tiltandheading: Treated as suggested values during framing. When omitted, both default to0°for a top-down, north-up view.rollandfov: Preserved as configured onMap3DElement.- Asynchronous child elements: Before rendering the initial view,
Map3DElementwaits for opted-in asynchronous children such as<gmp-route-3d>to finish loading route geometry. - Map and camera restrictions: Geographic
boundsand camera limits (minAltitude,maxAltitude,minTilt,maxTilt,minHeading, andmaxHeading) still constrain the autofitted view. For more information, see Restrict camera view and bounds.