GMSCollisionBehaviorRequired (Default): Always display the marker
regardless of collision. This is the default behavior. Has no impact on
whether any other markers or basemap labels show.
GMSCollisionBehaviorOptionalAndHidesLowerPriority: Display the marker only
if it does not overlap with other markers. If two markers of this type would
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.
GMSCollisionBehaviorRequiredAndHidesOptional: Always display the marker
regardless of collision, and hide any
GMSCollisionBehaviorOptionalAndHidesLowerPriority. Display the marker only
if it does not overlap with other markers. Does not
GMSCollisionBehaviorRequired. If two markers of this type would overlap,
the one with the higher zIndex is shown. Collision rules for markers with
the same zIndex are undefined.
Swift
// Defines a marker to always display and hide any marker or label overlay with this marker in the base mapmarker.collisionBehavior=.requiredAndHidesOptional
Objective-C
// Defines a marker to always display and hide any marker or label overlay with this marker in the base mapmarker.collisionBehavior=GMSCollisionBehaviorRequiredAndHidesOptional
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-18 UTC."],[[["\u003cp\u003eCollision behavior dictates how markers are displayed when they overlap on the map.\u003c/p\u003e\n"],["\u003cp\u003eYou can configure a marker's collision behavior using the \u003ccode\u003eGMSAdvancedMarker.collisionBehavior\u003c/code\u003e property with three options: \u003ccode\u003eGMSCollisionBehaviorRequired\u003c/code\u003e, \u003ccode\u003eGMSCollisionBehaviorOptionalAndHidesLowerPriority\u003c/code\u003e, and \u003ccode\u003eGMSCollisionBehaviorRequiredAndHidesOptional\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eGMSCollisionBehaviorRequired\u003c/code\u003e is the default, always displaying the marker regardless of overlap.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eGMSCollisionBehaviorOptionalAndHidesLowerPriority\u003c/code\u003e displays the marker only if it doesn't overlap with others, prioritizing higher \u003ccode\u003ezIndex\u003c/code\u003e and lower screen position in case of conflicts.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eGMSCollisionBehaviorRequiredAndHidesOptional\u003c/code\u003e always displays the marker and hides any with \u003ccode\u003eGMSCollisionBehaviorOptionalAndHidesLowerPriority\u003c/code\u003e behavior.\u003c/p\u003e\n"]]],["Collision behavior dictates marker display during overlaps. Options include: `Required` (always visible, default); `OptionalAndHidesLowerPriority` (visible only if no overlap, higher `zIndex` prevails); and `RequiredAndHidesOptional` (always visible, hides `OptionalAndHidesLowerPriority`). `zIndex` determines priority in overlapping markers, with lower vertical screen position breaking ties in specific cases. Setting `collisionBehavior` in code allows customization of display logic. It's recommended to use the same behavior for all advanced markers.\n"],null,["Select platform: [Android](/maps/documentation/android-sdk/advanced-markers/collision-behavior \"View this page for the Android platform docs.\") [iOS](/maps/documentation/ios-sdk/advanced-markers/collision-behavior \"View this page for the iOS platform docs.\") [JavaScript](/maps/documentation/javascript/advanced-markers/collision-behavior \"View this page for the JavaScript platform docs.\")\n\n\u003cbr /\u003e\n\nCollision behavior controls how a marker displays if it collides (overlaps) with\nanother marker.\n\nSet the collision behavior for a marker\n\n\nTo set collision behavior, set\n[`GMSAdvancedMarker.collisionBehavior`](/maps/documentation/ios-sdk/reference/objc/Classes/GMSAdvancedMarker#collisionbehavior) to\none of the following:\n\n- `GMSCollisionBehaviorRequired` (Default): Always display the marker\n regardless of collision. This is the default behavior. Has no impact on\n whether any other markers or basemap labels show.\n\n- `GMSCollisionBehaviorOptionalAndHidesLowerPriority`: Display the marker only\n if it does not overlap with other markers. If two markers of this type would\n overlap, the one with the higher `zIndex` is shown. If they have the same\n `zIndex`, the one with the lower vertical screen position is shown.\n\n- `GMSCollisionBehaviorRequiredAndHidesOptional`: Always display the marker\n regardless of collision, and hide any\n `GMSCollisionBehaviorOptionalAndHidesLowerPriority`. Display the marker only\n if it does not overlap with other markers. Does not\n `GMSCollisionBehaviorRequired`. If two markers of this type would overlap,\n the one with the higher `zIndex` is shown. Collision rules for markers with\n the same `zIndex` are undefined.\n\n | **Note:** For optimal collision behavior, create all advanced markers with the same type. This includes advanced markers represented with an [iconView](/maps/documentation/ios-sdk/advanced-markers/customization#use_the_iconview_property), icon or default capabilities.\n\nSwift \n\n```swift\n// Defines a marker to always display and hide any marker or label overlay with this marker in the base map\nmarker.collisionBehavior = .requiredAndHidesOptional\n```\n\nObjective-C \n\n```objective-c\n// Defines a marker to always display and hide any marker or label overlay with this marker in the base map\nmarker.collisionBehavior = GMSCollisionBehaviorRequiredAndHidesOptional\n```"]]
