Managing markers, labels, and POI collisions

AI-generated Key Takeaways

• The Beta version of the SDK used for marker collision management is deprecated; migrate to the GA release for advanced markers to control this behavior.

• Marker and label collision management requires using a map ID and is unavailable in lite mode with bitmap images.

• You can prioritize marker display using the Marker.CollisionBehavior property with options like REQUIRED, OPTIONAL_AND_HIDES_LOWER_PRIORITY, and REQUIRED_AND_HIDES_OPTIONAL.

• The CollisionBehavior property must be set during marker creation using AdvancedMarkerOptions and cannot be changed afterwards.

Beta SDK deprecation notice:

The Beta version of the SDK is deprecated and scheduled for decommissioning, and it's no longer available for new usage. The features described in this document are accessed using the Beta SDK. You can now use the GA release of advanced markers to control collision behavior.

See the release notes for more information. Use the Maps V3 BETA Migration Tool to help with migrating from the deprecated Beta version to a supported version.

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:

Kotlin

// Collision behavior can only be changed in the AdvancedMarkerOptions object.
// Changes to collision behavior after a marker has been created are not possible
val collisionBehavior: Int = CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL
val advancedMarkerOptions: AdvancedMarkerOptions = AdvancedMarkerOptions()
    .position(LatLng(10.0, 10.0))
    .collisionBehavior(collisionBehavior)

val marker: Marker = map.addMarker(advancedMarkerOptions) ?: error("Failed to add marker")

Java

// Collision behavior can only be changed in the AdvancedMarkerOptions object.
// Changes to collision behavior after a marker has been created are not possible
int collisionBehavior = AdvancedMarkerOptions.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL;
AdvancedMarkerOptions options = new AdvancedMarkerOptions()
        .position(new LatLng(10.0, 10.0))
        .collisionBehavior(collisionBehavior);

Marker marker = map.addMarker(options);