Drawio Syntax Connections

Draw.io Syntax: Connections

Purpose

This skill teaches how to connect shapes with edges in Draw.io mxGraph XML. It covers connection types, edge routing algorithms, waypoints, self-loops, custom connection points, and edge label positioning.

Critical Rules (Memorize These)

1. ALWAYS set edge="1" on every connector cell.
2. ALWAYS set source and target to valid vertex IDs. NEVER create edges without both attributes.
3. ALWAYS use relative="1" on edge <mxGeometry>.
4. NEVER hardcode waypoints when an edgeStyle can auto-route the path.
5. NEVER set both vertex="1" and edge="1" on the same cell.
6. ALWAYS use html=1 in the edge style when labels contain HTML.

Connection Types

Decision Tree: Which Connection Type?

Do you need the edge to attach at a SPECIFIC point on the shape?
  YES --> Fixed connection (set exitX/Y and/or entryX/Y in style)
  NO  --> Floating connection (omit exitX/Y and entryX/Y)

Is the edge connecting a shape to ITSELF?
  YES --> Self-loop (use edgeStyle=loopEdgeStyle)
  NO  --> Standard connection

Floating Connection (Default: Auto-Routes Along Perimeter)

Floating connections let Draw.io choose the optimal attachment points. The edge endpoint slides along the shape perimeter as shapes move.

<mxCell id="4" value="" style="edgeStyle=orthogonalEdgeStyle;html=1;"
        edge="1" source="2" target="3" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

When to use: ALWAYS prefer floating connections unless a specific attachment point is required by the diagram semantics.

Fixed Connection (Explicit Entry/Exit Points)

Fixed connections pin the edge to specific coordinates on the source and/or target shape. Coordinates are relative: (0,0) = top-left, (1,1) = bottom-right.

<mxCell id="4" value="" style="edgeStyle=orthogonalEdgeStyle;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;"
        edge="1" source="2" target="3" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

Connection Point Reference Grid

ALWAYS set exitDx=0;exitDy=0 and entryDx=0;entryDy=0 alongside exitX/Y and entryX/Y. These offset values default to undefined and MUST be explicitly zeroed for predictable behavior.

Exit/Entry Perimeter Projection

When exitPerimeter=1 (default), the exit coordinate is projected outward to the shape perimeter. For non-rectangular shapes with a matching perimeter style, this ensures the edge starts on the visible boundary.

Edge Routing Styles

Decision Tree: Which Edge Style?

What path shape do you need?
  Right-angle bends (most common)     --> edgeStyle=orthogonalEdgeStyle
  Single L-shaped or Z-shaped bend    --> edgeStyle=elbowEdgeStyle
  ER diagram with fixed-length stubs  --> edgeStyle=entityRelationEdgeStyle
  Manual segment control               --> edgeStyle=segmentEdgeStyle
  Horizontal side-to-side              --> edgeStyle=sideToSideEdgeStyle
  Vertical top-to-bottom               --> edgeStyle=topToBottomEdgeStyle
  Self-referencing loop                 --> edgeStyle=loopEdgeStyle
  Isometric (30-degree angles)          --> edgeStyle=isometricEdgeStyle
  Straight line (no routing)            --> omit edgeStyle entirely

Edge Style Reference

When no edgeStyle is set, the edge draws a straight line from source to target.

Edge Path Modifiers

Perimeter Spacing

Line Crossings

Waypoints

Waypoints are intermediate routing points that the edge MUST pass through. They are defined as <mxPoint> elements inside an <Array as="points">.

Decision Tree: Should You Use Waypoints?

Can the edgeStyle auto-route the path you need?
  YES --> Do NOT add waypoints. Let the router handle it.
  NO  --> Does the edge need to pass through specific coordinates?
           YES --> Add waypoints.
           NO  --> Choose a different edgeStyle.

Waypoint Syntax

<mxCell id="4" edge="1" source="2" target="3" parent="1"
        style="edgeStyle=orthogonalEdgeStyle;html=1;">
  <mxGeometry relative="1" as="geometry">
    <Array as="points">
      <mxPoint x="300" y="150" />
      <mxPoint x="300" y="250" />
    </Array>
  </mxGeometry>
</mxCell>

Waypoint coordinates are ALWAYS absolute canvas coordinates, NOT relative to the edge or its source/target shapes.

Waypoint Behavior Per Edge Style

Unconnected Edge Endpoints

When an edge has no source or target, use sourcePoint and targetPoint to define absolute start/end coordinates:

<mxCell id="5" edge="1" parent="1" style="edgeStyle=orthogonalEdgeStyle;html=1;">
  <mxGeometry relative="1" as="geometry">
    <mxPoint x="100" y="200" as="sourcePoint" />
    <mxPoint x="400" y="350" as="targetPoint" />
  </mxGeometry>
</mxCell>

ALWAYS prefer connected edges (source/target attributes) over sourcePoint/targetPoint. Unconnected edges break when shapes are moved.

Self-Loops

A self-loop connects a shape to itself. ALWAYS use edgeStyle=loopEdgeStyle.

<mxCell id="5" value="retry" style="edgeStyle=loopEdgeStyle;html=1;"
        edge="1" source="2" target="2" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

The source and target attributes MUST reference the same cell ID. Draw.io automatically routes the loop as a curved arc emerging from and returning to the shape.

Custom Connection Points on Shapes

Define fixed connection ports on a shape using the points style property. This restricts where edges can attach.

points=[[0.25,0],[0.5,0],[0.75,0],[0,0.5],[1,0.5],[0.25,1],[0.5,1],[0.75,1]];

Each [x,y] pair is a relative coordinate on the shape (same 0-1 range as exitX/exitY). When points is set, edges ONLY connect at these defined positions.

Port Constraints

Use portConstraint=eastwest on UML class diagram separator lines to force horizontal-only connections.

Edge Labels

Edge labels are positioned using x and y on the edge's <mxGeometry>.

Label Positioning Rules

Label at Center (Default)

<mxCell id="4" value="label text" style="edgeStyle=orthogonalEdgeStyle;html=1;"
        edge="1" source="2" target="3" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

When no x/y is set on the geometry, the label appears at the center of the edge path.

Label at Custom Position

<mxCell id="4" value="Yes" style="edgeStyle=orthogonalEdgeStyle;html=1;"
        edge="1" source="2" target="3" parent="1">
  <mxGeometry x="-0.5" y="-10" relative="1" as="geometry">
    <mxPoint as="offset" />
  </mxGeometry>
</mxCell>

This places the label at 25% from the source (x=-0.5), offset 10 pixels above/left of the edge path (y=-10).

Multiple Labels on One Edge

Create a separate vertex cell with connectable="0" and set it as a child of the edge:

<mxCell id="4" style="edgeStyle=orthogonalEdgeStyle;html=1;"
        edge="1" source="2" target="3" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="5" value="source label" style="edgeLabel;html=1;align=left;verticalAlign=bottom;"
        vertex="1" connectable="0" parent="4">
  <mxGeometry x="-0.8" y="0" relative="1" as="geometry">
    <mxPoint as="offset" />
  </mxGeometry>
</mxCell>
<mxCell id="6" value="target label" style="edgeLabel;html=1;align=right;verticalAlign=bottom;"
        vertex="1" connectable="0" parent="4">
  <mxGeometry x="0.8" y="0" relative="1" as="geometry">
    <mxPoint as="offset" />
  </mxGeometry>
</mxCell>

Edge label children: set vertex="1", connectable="0", and parent = the edge cell ID. Use the edgeLabel style. Position with x and y on their geometry (same range as edge labels).

Arrow Styles (Quick Reference)

Arrows are set via style properties. See drawio-core-styles for the full arrow catalog.

Common UML Arrow Patterns

Validation Checklist

Before delivering any diagram with connections, verify:

• Every edge has edge="1" set
• Every edge has both source and target referencing valid vertex IDs
• Every edge has <mxGeometry relative="1" as="geometry" />
• No unnecessary waypoints (edgeStyle handles routing)
• Self-loops use edgeStyle=loopEdgeStyle with source = target
• Fixed connections include exitDx=0;exitDy=0 and entryDx=0;entryDy=0
• Edge labels use x range -1 to 1 and y in pixels
• html=1 present in style when label contains HTML

References

• references/methods.md — Complete property reference for edges and connections
• references/examples.md — Working XML examples for every connection pattern
• references/anti-patterns.md — What NOT to do with connections