Adaptive label positioning: no global collision avoidance or diagonal fallback
Is your feature request related to a problem? Please describe
AdaptiveLabelPositioningBehavior improves external label placement (events, gateways, boundary events) by moving a label to a free side, but it is a purely local heuristic and has gaps that leave labels overlapping other diagram content:
No global collision avoidance. It only considers the element's own incoming/outgoing connections (
getTakenConnectionAlignments) and, for boundary events, the host orientation (getTakenHostAlignments). It does not check overlap against other shapes, other elements' flows, or other labels in the diagram. A label can be moved to a "free" side that lands directly on top of a neighbouring shape or an unrelated sequence/message flow.No diagonal fallback.
ALIGNMENTSis axis-only (top,bottom,left,right). When all four axis-aligned sides are taken,getOptimalPositionreturnsfreeAlignments[0]orundefined, so the label is left at its default position (often overlapping). This is especially common for boundary events, where the host occupies one side and attached/nearby flows occupy the others, so no axis side is regularly available.
Describe the solution you'd like
Extend adaptive label positioning toward a fuller "auto-place" model:
- Consider all nearby geometry when scoring candidate positions — other shapes (same scope), sequence + message flows (any scope), and other labels — not just the element's own connections + host.
- Add a diagonal fallback when no axis-aligned side is collision-free (particularly for boundary events), choosing the diagonal based on the boundary/host position.
- Preference order: axis-aligned (centered)
bottom → top → left → right, then diagonal. - Invariant to preserve: a boundary-event label must never overlap its host shape.
Describe alternatives you've considered
Keeping the local heuristic and accepting occasional overlaps (status quo). This is insufficient for dense diagrams and for automatic layouting, where labels are placed without a human to nudge them.
Additional context
Surfaced while building an automatic BPMN layout engine, where label placement must be collision-free without manual correction. Happy to contribute / discuss the scoring approach.
Source: bpmn-io/bpmn-js