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, setAdvancedMarkerElement.collisionBehaviorto one of
the following:
REQUIRED: (default) Always display the marker regardless of collision.
OPTIONAL_AND_HIDES_LOWER_PRIORITYDisplay the marker only if it does not
overlap with other markers. If two markers of this type would overlap, the one
with the higherzIndexis shown. If they have the samezIndex, the one with
the lower vertical screen position is shown.
REQUIRED_AND_HIDES_OPTIONALAlways display the marker regardless of
collision, and hide anyOPTIONAL_AND_HIDES_LOWER_PRIORITYmarkers or labels
that would overlap with the marker.
The following example shows setting collision behavior for a marker:
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 aLatLngAltitudeas the value for theMarkerView.positionoption:
TypeScript
constpin=newPinElement({background:'#4b2e83',borderColor:'#b7a57a',glyphColor:'#b7a57a',scale:2.0,});constmarkerView=newAdvancedMarkerElement({map,content:pin.element,// Set altitude to 20 meters above the ground.position:{lat:47.65170843460547,lng:-122.30754,altitude:20}asgoogle.maps.LatLngAltitudeLiteral,});
constpin=newPinElement({background:'#4b2e83',borderColor:'#b7a57a',glyphColor:'#b7a57a',scale:2.0,});constmarkerView=newAdvancedMarkerElement({map,content:pin.element,// Set altitude to 20 meters above the ground.position:{lat:47.65170843460547,lng:-122.30754,altitude:20},});
See the markers' visibility change (begin by zooming out):
To control the visibility of an Advanced Marker, create azoom_changedlistener, and add a conditional function to setAdvancedMarkerElement.maptonullif the zoom exceeds the specified level, as shown in the following
example:
TypeScript
map.addListener('zoom_changed',()=>{constzoom=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;}});
map.addListener('zoom_changed',()=>{constzoom=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;}});
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[[["\u003cp\u003eThis documentation explains how to manage Advanced Markers, including collision behavior, altitude, and visibility based on zoom level.\u003c/p\u003e\n"],["\u003cp\u003eYou can control marker display during overlaps using \u003ccode\u003eAdvancedMarkerElement.collisionBehavior\u003c/code\u003e with options like \u003ccode\u003eREQUIRED\u003c/code\u003e, \u003ccode\u003eOPTIONAL_AND_HIDES_LOWER_PRIORITY\u003c/code\u003e, and \u003ccode\u003eREQUIRED_AND_HIDES_OPTIONAL\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eOn vector maps, adjust marker altitude using \u003ccode\u003eLatLngAltitude\u003c/code\u003e for the \u003ccode\u003eMarkerView.position\u003c/code\u003e to integrate with 3D map elements.\u003c/p\u003e\n"],["\u003cp\u003eManage marker visibility based on zoom levels by implementing a \u003ccode\u003ezoom_changed\u003c/code\u003e listener that conditionally sets \u003ccode\u003eAdvancedMarkerElement.map\u003c/code\u003e to control display.\u003c/p\u003e\n"],["\u003cp\u003eAdvanced Markers are supported on Android, iOS, and JavaScript platforms with respective documentation available.\u003c/p\u003e\n"]]],["This content details controlling Advanced Marker behavior on maps. Key actions include setting `collisionBehavior` to `REQUIRED`, `OPTIONAL_AND_HIDES_LOWER_PRIORITY`, or `REQUIRED_AND_HIDES_OPTIONAL` to manage marker overlap. Altitude is set using `LatLngAltitude` in the `position` parameter, enabling 3D placement. Marker visibility can be managed with zoom levels by using a `zoom_changed` listener and setting `AdvancedMarkerElement.map` to `null` when the zoom is outside a defined range.\n"],null,["Select platform: [Android](/maps/documentation/android-sdk/advanced-markers/collision-behavior \"View this page for the Android platform docs.\") [iOS](/maps/documentation/ios-sdk/advanced-markers/collision-behavior \"View this page for the iOS platform docs.\") [JavaScript](/maps/documentation/javascript/advanced-markers/collision-behavior \"View this page for the JavaScript platform docs.\")\n\n\u003cbr /\u003e\n\nThis page shows you how to control the following aspects of Advanced Markers:\n\n- Set collision behavior for a marker\n- Set marker altitude\n- Control marker visibility by map zoom level\n\nSet collision behavior for a marker\n\n\nCollision behavior controls how a marker will display if it collides (overlaps)\nwith another marker. Collision behavior is only supported on vector maps.\n\nTo set collision behavior, set `AdvancedMarkerElement.collisionBehavior` to one of\nthe following:\n\n- `REQUIRED`: (default) Always display the marker regardless of collision.\n- `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.\n- `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.\n\n| **Note:** On raster maps, only marker-to-marker collisions are detected. Marker collisions with basemap labels are supported only on vector maps.\n\nThe following example shows setting collision behavior for a marker:\n\n\nTypeScript \n\n```typescript\nconst advancedMarker = new AdvancedMarkerElement({\n position: new google.maps.LatLng({ lat, lng }),\n map,\n collisionBehavior: collisionBehavior,\n});https://github.com/googlemaps-samples/js-api-samples/blob/7a62b25fe463fc0fd06949fcd1029aecc8b8504b/dist/samples/advanced-markers-collision/docs/index.ts#L64-L68\n```\n| **Note:** Read the [guide](/maps/documentation/javascript/using-typescript) on using TypeScript and Google Maps.\n\nJavaScript \n\n```javascript\nconst advancedMarker = new AdvancedMarkerElement({\n position: new google.maps.LatLng({ lat, lng }),\n map,\n collisionBehavior: collisionBehavior,\n});https://github.com/googlemaps-samples/js-api-samples/blob/7a62b25fe463fc0fd06949fcd1029aecc8b8504b/dist/samples/advanced-markers-collision/docs/index.js#L49-L53\n```\n\n\u003cbr /\u003e\n\nSet marker altitude\n\n\nOn vector maps, you can set the altitude at which a marker appears. This is\nuseful for making markers appear correctly in relation to 3D map content. To set\nthe altitude for a marker, specify a `LatLngAltitude` as the value for the\n`MarkerView.position` option:\n\n\nTypeScript \n\n```typescript\nconst pin = new PinElement({\n background: '#4b2e83',\n borderColor: '#b7a57a',\n glyphColor: '#b7a57a',\n scale: 2.0,\n});\n\nconst markerView = new AdvancedMarkerElement({\n map,\n content: pin.element,\n // Set altitude to 20 meters above the ground.\n position: { lat: 47.65170843460547, lng: -122.30754, altitude: 20 } as google.maps.LatLngAltitudeLiteral,\n});https://github.com/googlemaps-samples/js-api-samples/blob/7a62b25fe463fc0fd06949fcd1029aecc8b8504b/dist/samples/advanced-markers-altitude/docs/index.ts#L22-L34\n```\n| **Note:** Read the [guide](/maps/documentation/javascript/using-typescript) on using TypeScript and Google Maps.\n\nJavaScript \n\n```javascript\nconst pin = new PinElement({\n background: '#4b2e83',\n borderColor: '#b7a57a',\n glyphColor: '#b7a57a',\n scale: 2.0,\n});\nconst markerView = new AdvancedMarkerElement({\n map,\n content: pin.element,\n // Set altitude to 20 meters above the ground.\n position: { lat: 47.65170843460547, lng: -122.30754, altitude: 20 },\n});https://github.com/googlemaps-samples/js-api-samples/blob/7a62b25fe463fc0fd06949fcd1029aecc8b8504b/dist/samples/advanced-markers-altitude/docs/index.js#L21-L32\n```\n\n\u003cbr /\u003e\n\nControl marker visibility by map zoom level\n\nSee the markers' visibility change (begin by zooming out):\n\n\nTo control the visibility of an Advanced Marker, create a `zoom_changed`\nlistener, and add a conditional function to set `AdvancedMarkerElement.map` to\n`null` if the zoom exceeds the specified level, as shown in the following\nexample:\n\n\nTypeScript \n\n```typescript\nmap.addListener('zoom_changed', () =\u003e {\n const zoom = map.getZoom();\n if (zoom) {\n // Only show each marker above a certain zoom level.\n marker01.map = zoom \u003e 14 ? map : null;\n marker02.map = zoom \u003e 15 ? map : null;\n marker03.map = zoom \u003e 16 ? map : null;\n marker04.map = zoom \u003e 17 ? map : null;\n }\n});https://github.com/googlemaps-samples/js-api-samples/blob/7a62b25fe463fc0fd06949fcd1029aecc8b8504b/dist/samples/advanced-markers-zoom/docs/index.ts#L44-L53\n```\n| **Note:** Read the [guide](/maps/documentation/javascript/using-typescript) on using TypeScript and Google Maps.\n\nJavaScript \n\n```javascript\nmap.addListener('zoom_changed', () =\u003e {\n const zoom = map.getZoom();\n if (zoom) {\n // Only show each marker above a certain zoom level.\n marker01.map = zoom \u003e 14 ? map : null;\n marker02.map = zoom \u003e 15 ? map : null;\n marker03.map = zoom \u003e 16 ? map : null;\n marker04.map = zoom \u003e 17 ? map : null;\n }\n});https://github.com/googlemaps-samples/js-api-samples/blob/7a62b25fe463fc0fd06949fcd1029aecc8b8504b/dist/samples/advanced-markers-zoom/docs/index.js#L38-L47\n```\n\n\u003cbr /\u003e\n\nNext steps\n\n[Make markers clickable and accessible](/maps/documentation/javascript/advanced-markers/accessible-markers)"]]
