Collision behavior

Select platform: Android iOS JavaScript

This page shows you how to control the collision behavior for a marker.

Set collision behavior for a marker

Collision behavior controls how a marker displays if it collides (overlaps) with another marker. The way you create an advanced markers determines how collision behavior works:

  • Advanced markers created by using BitmapDescriptorFactory are referred to as bitmap markers. These markers are drawn by the core map.

  • All other advanced markers, including those created by using the AdvancedMarkerOptions.iconView() method, are referred to as view markers and are drawn on a layer above the core map.

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

  • CollisionBehavior.REQUIRED: (default) Always display the marker regardless of collision.
  • CollisionBehavior.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.

  • CollisionBehavior.OPTIONAL_AND_HIDES_LOWER_PRIORITY Display the marker only if it does not overlap with other markers.

    • If two bitmap markers 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. For more information about the zIndex, see Marker z-index.

    • If two view markers overlap, the one with the higher zIndex is shown. If they have the same zIndex, the last created marker overlaps any markers created before it.

    • Because view markers are drawn on a layer above bitmap markers, view markers overlap bitmap markers. Therefore, you should try to use markers of the same type for better collision control.

The following example shows setting collision behavior for a 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);