4. Connectors and Smart Route

Making a connection#

Hover a shape and its eight ports appear — n ne e se s sw w nw — just outside the outline (they stay up for a moment after the pointer leaves, so you can reach them). Drag from one:

• onto another shape → connected shape to shape;
• onto a specific port of another shape → that port is pinned;
• into empty space → a new shape is created at the drop point, connected, and put into text editing.

The C tool does the same thing without needing the ports: drag from anywhere inside a shape.

A connection whose ends are not pinned lets the router pick the faces; that is almost always what you want, because the faces are then re-chosen as the shapes move.

Routing modes#

Per connector, from the right-click Routing submenu or the Inspector:

Only orthogonal connectors with no hand-placed waypoints take part in the whole-graph routing pass described below.

Smart Route#

The Smart Route toggle in the toolbar (R) is what makes connectors go around shapes instead of through them.

Under the hood it is not a per-edge trick — the whole page is routed in one pass:

1. Face choice. Each connector is routed once to learn which face of each shape it wants to leave from and arrive at.
2. Port distribution. Every face that ends up carrying more than one connector spreads its attachments along that face, ordered by where the other end sits, so five connectors arriving at one box no longer stack on one pixel. A port you pinned by hand is never moved.
3. Re-route. Each connector is routed again with the shared slots. The router is an A* over a visibility lattice built from the clearance borders of the obstacles, with direction in the search state so bends are costed properly, and a guaranteed escape ring outside the scene so there is always some clean path — there is no "give up and cut through everything" fallback.
4. Lane separation. Interior runs that different connectors would draw on top of one another are pushed into parallel lanes 9 px apart. Only runs that touch neither port may move, and any shift that would drive a route into a shape is rolled back, so this can improve the picture but never breaks the no-penetration guarantee.

Containers and backdrops are routed through, not around: lane, plane, group, fragment, lifeline and text are not obstacles.

The result is memoised on the geometry, so a re-render that changes nothing re-uses the previous answer.

Exports use the same routes. The export dialog's Route connectors around shapes option defaults to on precisely so an export cannot differ from the screen.

Crossovers#

Crossovers (J) draws a small hop where one connector crosses another. The convention is that horizontal runs jump vertical ones, so a crossing is drawn exactly once no matter which connector renders first.

Shaping a route by hand#

With a connector selected:

• Waypoint handles — drag the round handles to place explicit points.
• Alt-click the line to insert a waypoint where you clicked.
• Segment dragging — drag a straight run perpendicular to itself. The point count never changes, so dragging reshapes the route rather than littering it with new points. The first and last segments touch the ports and are not draggable.
• Endpoint dragging — drag either end onto another shape or port to re-wire it, or into space to leave it floating.
• Label dragging — drag the label along the line to move its position.
• Right-click → Clear waypoints returns the connector to a fully automatic route.

A connector with waypoints is routed through them with corners inserted so every segment stays axis-aligned; it opts out of the whole-graph pass.

Arrow heads#

Right-click → Start/End arrow head, the Inspector, or the palette (Connector end: …). The set is: none, filled arrow, open arrow, solid triangle, diamond, circle, bar, the UML heads (generalisation, aggregation, composition) and the five crow's-foot heads (exactly one, many, zero or one, one or many, zero or many). All of them are drawn on the canvas and in SVG, PDF and draw.io exports.

Swap ends reverses a connector, taking the heads with it.

Self-connections#

A connector whose two ends are the same shape is drawn as a small rounded loop off a free face, rather than degenerating to a zero-length path.

Routing modes#

The Inspector's Routing field sets how one connector is drawn:

Straight and curved connectors take no crossing hops — there is nothing axis-aligned to splice an arc into — and are not bundled.

Buses#

When three or more connectors run between two containers, they are re-drawn as spur → shared trunk → spur instead of as separate parallel lines, the way a wiring diagram does it. You can also state a bus by hand: put the same name in the Inspector's Bus field on each connector that belongs to it.

Membership is never guessed from bare geometry. Merging connectors onto a trunk loses which spur pairs with which, so it needs the author to say so — either by grouping the endpoints or by naming the bus.

Bundling#

Connectors that share a corridor are re-seated on evenly spaced lanes rather than being left to overlap. Only the interior runs move: ports stay where they are, and a move that would graze a shape or collapse a neighbouring run is rolled back rather than applied.

Labels#

A connector label with no position of its own slides along the route to the first spot clear of shapes, of that connector's own handles, and of every label already placed. Drag the label and it is pinned there — pinned labels are placed first and the automatic ones move out of their way. Clear waypoints does not unpin a label; drag it back to the middle to re-pin it there.