Connector labels

Connector labels are the words attached to a line. In a crowded drawing they can overlap equipment shapes or each other and become unreadable. Arrange labels moves the words into nearby free space; it does not reroute the line or move the equipment. It runs only when requested, not during every drag.

Choose Crowd labels to place two labels together over a shape, then Arrange labels to move them into available space. Undo restores their previous positions in one step. Try the same sequence with plain text and large badges.

session.arrangeLabels().requireAllowed();
// Or arrange selected connections while respecting all other labels.
session.arrangeLabels(connectorIds: ['journey'], spacing: 12).requireAllowed();

requireAllowed() means "throw an error if this edit is rejected." The example shell catches that error and displays its message. Applications can instead check the returned result's allowed and reason properties.

Arrangement uses measured text and badge bounds, preserving placements that already fit. Positions are saved with the drawing and remain manually editable. This explicit action does not continuously reposition labels while you edit. It avoids leaf shapes and other labels, using a bounded set of nearby positions; it does not guarantee a global optimum or avoid every crossing line. If no placement fits, the operation reports a message and changes nothing. Locked connectors and connectors owned by groups are rejected in this initial version.

Loading interactive example…Open in new tab ↗

Opening the live canvas…

A picnic journey starts with one label. Select the connection and press Enter to edit its first label; double-click a label to edit that label. The framework owns those interactions. Enter adds a new line; Escape finishes editing. Labels support plain paragraphs and inline formatting, without lists. The editing outline stays visible while typing, and an empty label reserves one character's width.

Use Add label for a second attachment. The default grammar permits two; a third request shows a denial without editing the document. First label and Last label choose the target for the other actions. With no label selected, actions target the first remaining label.

Action / public API	What changes
addConnectorLabel	Creates one attachment with its text and path fraction as one undo step.
selectConnectorLabel	Selects an individual label without changing history.
updateConnectorLabel(..., fraction: ...)	Moves the selected label along the path. You can also drag it.
updateConnectorLabel(..., story: ..., presentation: ...)	Changes that label's text size/color and badge together; preserves the other label and connector endpoints.
removeConnectorLabel	Removes one label. Undo restores its text, position and style.

Large badge applies 20px text and a subtle bordered surface. Plain text returns to 14px text without a backing surface. The example offers fixed choices to demonstrate the API; the playground inspector exposes more styling controls.

Try styling the second label, moving it, deleting it, then stepping backward through Undo. Reset restores the initial document with empty history. JSON persistence preserves both labels and their presentation.

See Connectors and Text.

With accessibility enabled, each nonempty visible label has its own Connector label target. Activating it selects that label; Enter edits it and Delete uses the same protected command as canvas interaction. The whole connector remains available as an aggregate target.

Source

void addExampleLabel(DrawingSession s) {
  final suffix = s.document.revision;
  final id = s.addConnectorLabel(
    'journey',
    fraction: .7,
    story: TextStory.paragraph(
      id: 'label-story-$suffix',
      blockId: 'label-block-$suffix',
      text: 'Nearly there',
    ),
  );
  s.selectConnectorLabel('journey', id);
}