Managing markers, labels, and POI collisions

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.

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.
  • OptionalAndHidesLowerPriority - Indicates that the marker may be replaced or overlapped by a required marker, or replaced by an OptionalAndHidesLowerPriority marker with higher priority. Use zIndex to help determine relative priority between OptionalAndHidesLowerPriority markers. A higher zIndex value indicates higher priority.
  • RequiredAndHidesOptional - Requires display of a marker while hiding any OptionalAndHidesLowerPriority 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:


let position = CLLocationCoordinate2D(latitude: 47.0169, longitude: -122.336471)
let marker = GMSMarker(position: position)
marker.zIndex = 10
marker.collisionBehavior = GMSCollisionBehavior.optionalAndHidesLowerPriority = mapView


CLLocationCoordinate2D position = CLLocationCoordinate2DMake(47.0169, -122.336471);
GMSMarker *marker = [GMSMarker markerWithPosition:position];
marker.zIndex = 10;
marker.collisionBehavior = GMSCollisionBehaviorOptionalAndHidesLowerPriority; = mapView;