Interface: MarkerLayoutConfig

Configuration for automatic marker label collision avoidance.

When enabled, a marker’s text label (see MarkerConfig.textPosition) is treated as a preferred starting side rather than a fixed placement: the SDK checks it against neighboring markers’ icons and labels, moves it to a free side (right/top/left/bottom) when its preferred side is occupied, and hides it entirely when no side is collision-free. The marker’s icon itself never moves.

Example


const markerLayoutConfig: MarkerLayoutConfig = {
  enabled: true,
  minZoomForLabels: 17,
  gapPx: 8,
  maxLabelWidthPx: 160,
}

Properties

enabled?


optional enabled?: boolean;

Enable automatic label collision avoidance. When false, labels always render at their configured textPosition, exactly like before this feature existed.

Default


true

gapPx?


optional gapPx?: number;

Horizontal gap, in pixels, between an icon and a label placed to its left or right. Drives both the collision math and the rendered offset (published as the --mapvx-label-gap CSS custom property).

Default

maxLabelWidthPx?


optional maxLabelWidthPx?: number;

Default maximum label width, in pixels, before truncation. Applied to every marker added through addMarker, and overridable per marker via MarkerConfig.maxLabelWidthPx.

Default

minZoomForLabels?


optional minZoomForLabels?: number;

Zoom level below which no label is rendered at all. Markers keep their icons; only the text is withheld.

Motivated by dense maps: zoomed out, hundreds of pins share a few hundred pixels and nearly every label would be hidden by collision avoidance anyway, one at a time and in an order the caller cannot predict. A single threshold makes that state deliberate and uniform — pins only, then labels once the camera is close enough for them to fit.

Evaluated continuously as the camera moves, so labels appear the moment the zoom crosses the threshold rather than when the gesture ends.

Labels withheld by this threshold are not obstacles: they never occupy space for their neighbors, so nothing is displaced on their behalf.

Requires enabled: true: enabled: false short-circuits the entire layout pass, so the threshold is never evaluated either.

Default


-Infinity (no threshold — labels are placed at every zoom)

paddingPx?


optional paddingPx?: number;

Extra buffer, in pixels, added around every box when testing for collisions between a marker and its neighbors. Higher values leave more visual breathing room between labels/icons at the cost of hiding labels sooner under crowding. A label’s distance from its own icon is set by gapPx/verticalGapPx alone and is unaffected by this.

Default

verticalGapPx?


optional verticalGapPx?: number;

Vertical gap, in pixels, between an icon and a label placed above or below it. Drives both the collision math and the rendered offset (published as the --mapvx-label-vertical-gap CSS custom property).