Control collision behavior, altitude, and visibility

  • This documentation explains how to manage Advanced Markers, including collision behavior, altitude, and visibility based on zoom level.

  • You can control marker display during overlaps using AdvancedMarkerElement.collisionBehavior with options like REQUIRED, OPTIONAL_AND_HIDES_LOWER_PRIORITY, and REQUIRED_AND_HIDES_OPTIONAL.

  • On vector maps, adjust marker altitude using LatLngAltitude for the MarkerView.position to integrate with 3D map elements.

  • Manage marker visibility based on zoom levels by implementing a zoom_changed listener that conditionally sets AdvancedMarkerElement.map to control display.

  • Advanced Markers are supported on Android, iOS, and JavaScript platforms with respective documentation available.
Select platform: Android iOS JavaScript

This page shows you how to control the following aspects of Advanced Markers:

  • Set collision behavior for a marker
  • Set marker altitude
  • Control marker visibility by map zoom level

Set collision behavior for a marker

Collision behavior controls how a marker will display if it collides (overlaps) with another marker. Collision behavior is only supported on vector maps.

To set collision behavior, set AdvancedMarkerElement.collisionBehavior to one of the following:

  • REQUIRED: (default) Always display the marker regardless of collision.
  • OPTIONAL_AND_HIDES_LOWER_PRIORITY Display the marker only if it does not overlap with other markers. If two markers of this type would overlap, the one with the higher zIndex is shown. If they have the same zIndex, the one with the lower vertical screen position is shown.
  • REQUIRED_AND_HIDES_OPTIONAL Always display the marker regardless of collision, and hide any OPTIONAL_AND_HIDES_LOWER_PRIORITY markers or labels that would overlap with the marker.

The following example shows setting collision behavior for a marker:

TypeScript

const advancedMarker = new AdvancedMarkerElement({
  position: new google.maps.LatLng({ lat, lng }),
  map,
  collisionBehavior: collisionBehavior,
});
index.ts

JavaScript

const advancedMarker = new AdvancedMarkerElement({
    position: new google.maps.LatLng({ lat, lng }),
    map,
    collisionBehavior: collisionBehavior,
});
index.js

Set marker altitude

On vector maps, you can set the altitude at which a marker appears. This is useful for making markers appear correctly in relation to 3D map content. To set the altitude for a marker, specify a LatLngAltitude as the value for the MarkerView.position option:

TypeScript

const pin = new PinElement({
    background: '#4b2e83',
    borderColor: '#b7a57a',
    glyphColor: '#b7a57a',
    scale: 2.0,
});

const markerView = new AdvancedMarkerElement({
    map,
    content: pin.element,
    // Set altitude to 20 meters above the ground.
    position: { lat: 47.65170843460547, lng: -122.30754, altitude: 20 } as google.maps.LatLngAltitudeLiteral,
});
index.ts

JavaScript

const pin = new PinElement({
    background: '#4b2e83',
    borderColor: '#b7a57a',
    glyphColor: '#b7a57a',
    scale: 2.0,
});
const markerView = new AdvancedMarkerElement({
    map,
    content: pin.element,
    // Set altitude to 20 meters above the ground.
    position: { lat: 47.65170843460547, lng: -122.30754, altitude: 20 },
});
index.js

Control marker visibility by map zoom level

See the markers' visibility change (begin by zooming out):

To control the visibility of an Advanced Marker, create a zoom_changed listener, and add a conditional function to set AdvancedMarkerElement.map to null if the zoom exceeds the specified level, as shown in the following example:

TypeScript

map.addListener('zoom_changed', () => {
    const zoom = map.getZoom();
    if (zoom) {
        // Only show each marker above a certain zoom level.
        marker01.map = zoom > 14 ? map : null;
        marker02.map = zoom > 15 ? map : null;
        marker03.map = zoom > 16 ? map : null;
        marker04.map = zoom > 17 ? map : null;
    }
});
index.ts

JavaScript

map.addListener('zoom_changed', () => {
    const zoom = map.getZoom();
    if (zoom) {
        // Only show each marker above a certain zoom level.
        marker01.map = zoom > 14 ? map : null;
        marker02.map = zoom > 15 ? map : null;
        marker03.map = zoom > 16 ? map : null;
        marker04.map = zoom > 17 ? map : null;
    }
});
index.js

Next steps

Make markers clickable and accessible