New map styling is coming soon to Google Maps Platform. This update to map styling includes a new default color palette and improvements to map experiences and usability. All map styles will be automatically updated in March 2025. For more information on availability and how to opt in earlier, see New map style for Google Maps Platform.

Manage 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.

Before you begin

To manage marker and label collisions, you must be using a map id enabled with vector image type.

Specifying marker priorities

Use the AdvancedMarkerElement.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.

For more information, see the Marker Collision Management code sample.