Stay organized with collections
Save and categorize content based on your preferences.
This page shows you how to manage collisions between markers that you add
to your map and default labels, such as points of interest (POIs) or street
names.
Before you begin
To manage marker and label collisions, you must be using a
map id.
If you're using a bitmap image of a map through lite mode, you can't
manage marker and label collisions.
Specifying marker priorities
Use the Marker.CollisionBehavior property to specify priority on a
marker.
Use one of the following values:
REQUIRED - Default. Requires display of a marker that overlaps with other
markers, labels, and POIs.
OPTIONAL_AND_HIDES_LOWER_PRIORITY - Indicates that the marker may be replaced or
overlapped by a required marker, or replaced by an OPTIONAL_AND_HIDES_LOWER_PRIORITY
marker with higher priority. Use zIndex to help determine relative priority
between OPTIONAL_AND_HIDES_LOWER_PRIORITY markers. A higher zIndex value indicates
higher priority.
REQUIRED_AND_HIDES_OPTIONAL - Requires display of a marker while hiding
any OPTIONAL_AND_HIDES_LOWER_PRIORITY markers, labels, or POIs that overlap with the
marker. The marker may overlap with other required markers.
The following code example shows setting CollisionBehavior for a new marker:
[null,null,["Last updated 2025-08-28 UTC."],[[["\u003cp\u003eThe Beta version of the SDK used for marker collision management is deprecated; migrate to the GA release for advanced markers to control this behavior.\u003c/p\u003e\n"],["\u003cp\u003eMarker and label collision management requires using a map ID and is unavailable in lite mode with bitmap images.\u003c/p\u003e\n"],["\u003cp\u003eYou can prioritize marker display using the \u003ccode\u003eMarker.CollisionBehavior\u003c/code\u003e property 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\u003eThe \u003ccode\u003eCollisionBehavior\u003c/code\u003e property must be set during marker creation using \u003ccode\u003eAdvancedMarkerOptions\u003c/code\u003e and cannot be changed afterwards.\u003c/p\u003e\n"]]],["The Beta SDK is deprecated; use the GA release of advanced markers instead. Use the Migration Tool to transition from the Beta version. To manage marker and label collisions, use a map ID, not lite mode. Set marker priority with the `CollisionBehavior` property, choosing from `REQUIRED`, `OPTIONAL_AND_HIDES_LOWER_PRIORITY`, or `REQUIRED_AND_HIDES_OPTIONAL`. Higher `zIndex` values indicate higher priority for optional markers. `CollisionBehavior` can only be set in the `AdvancedMarkerOptions` object when the marker is created.\n"],null,["| **Beta SDK deprecation notice:**\n|\n| The Beta version of the SDK is deprecated and scheduled for decommissioning,\n| and it's no longer available for new usage. The features described in this\n| document are accessed using the Beta SDK. You can now use the GA release of\n| advanced markers to\n| [control collision behavior](/maps/documentation/android-sdk/advanced-markers/collision-behavior).\n|\n| See the [release notes](/maps/documentation/android-sdk/releases#2021-08-18) for more information.\n| Use the [Maps V3 BETA\n| Migration Tool](https://github.com/googlemaps/android-v3-migration) to help with migrating from the deprecated Beta version to a\n| supported version.\n\nThis page shows you how to manage collisions between markers that you add\nto your map and default labels, such as points of interest (POIs) or street\nnames.\n\n\u003cbr /\u003e\n\nBefore you begin\n\nTo manage marker and label collisions, you must be using a\n[map id](/maps/documentation/android-sdk/cloud-based-map-styling#creating-map-ids).\nIf you're using a bitmap image of a map through [lite mode](/maps/documentation/android-sdk/lite), you can't manage marker and label collisions.\n\nSpecifying marker priorities\n\nUse the `Marker`.`CollisionBehavior` property to specify priority on a\nmarker.\n\nUse one of the following values:\n\n- `REQUIRED` - Default. Requires display of a marker that overlaps with other markers, labels, and POIs.\n- `OPTIONAL_AND_HIDES_LOWER_PRIORITY` - Indicates that the marker may be replaced or overlapped by a required marker, or replaced by an `OPTIONAL_AND_HIDES_LOWER_PRIORITY` marker with higher priority. Use `zIndex` to help determine relative priority between `OPTIONAL_AND_HIDES_LOWER_PRIORITY` markers. A higher `zIndex` value indicates higher priority.\n- `REQUIRED_AND_HIDES_OPTIONAL` - Requires display of a marker while hiding any `OPTIONAL_AND_HIDES_LOWER_PRIORITY` markers, labels, or POIs that overlap with the marker. The marker may overlap with other required markers.\n\nThe following code example shows setting `CollisionBehavior` for a new marker: \n\nKotlin \n\n```kotlin\n// Collision behavior can only be changed in the AdvancedMarkerOptions object.\n// Changes to collision behavior after a marker has been created are not possible\nval collisionBehavior: Int = CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL\nval advancedMarkerOptions: AdvancedMarkerOptions = AdvancedMarkerOptions()\n .position(LatLng(10.0, 10.0))\n .collisionBehavior(collisionBehavior)\n\nval marker: Marker = map.addMarker(advancedMarkerOptions) ?: error(\"Failed to add marker\")\n```\n\nJava \n\n```java\n// Collision behavior can only be changed in the AdvancedMarkerOptions object.\n// Changes to collision behavior after a marker has been created are not possible\nint collisionBehavior = AdvancedMarkerOptions.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL;\nAdvancedMarkerOptions options = new AdvancedMarkerOptions()\n .position(new LatLng(10.0, 10.0))\n .collisionBehavior(collisionBehavior);\n\nMarker marker = map.addMarker(options);\n```"]]
