Control collision behavior

Select platform: Android iOS JavaScript

This page demonstrates how to set the collision behavior for a marker. Collision behavior controls how a marker will display if it collides (overlaps) with another marker.

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

  • REQUIRED: Always display the marker regardless of collision
  • 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.
  • OPTIONAL_AND_HIDES_LOWER_PRIORITY: 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.

The following example shows setting collision behavior for a marker:

const marker = new Marker3DElement({
    position: { lat, lng },
    // Try setting a different collision behavior here.
    collisionBehavior: 'REQUIRED',
});

Control the collision behavior of a label

You can control the collision behavior of a marker's pin and label text separately. In some instances, it might be beneficial to hide labels while leaving marker pins visible on the screen to preserve context. To do this, add a <gmp-label-3d> element as a sibling of <gmp-marker-3d> and link them using the for attribute.

The following code sample demonstrates setting collision behavior for a label separately from a marker:

const markerWithIndependentLabel = new Marker3DElement({
    position: { lat: 37.423, lng: -122.015 },
});
markerWithIndependentLabel.id = 'marker-1';
const label = new Label3DElement({
    collisionBehavior: CollisionBehavior.OPTIONAL_AND_HIDES_LOWER_PRIORITY,
    for: 'marker-1',
});
label.append('Independent label example');
map.append(markerWithIndependentLabel);
map.append(label);