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 ``.
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.

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.

Connection Point Reference Grid

| Position | X | Y | Description | |----------|-----|-----|-------------| | Top-left | 0 | 0 | Upper-left corner | | Top-center | 0.5 | 0 | Middle of top edge | | Top-right | 1 | 0 | Upper-right corner | | Middle-left | 0 | 0.5 | Center of left edge | | Center | 0.5 | 0.5 | Shape center | | Middle-right | 1 | 0.5 | Center of right edge | | Bottom-left | 0 | 1 | Lower-left corner | | Bottom-center | 0.5 | 1 | Middle of bottom edge | | Bottom-right | 1 | 1 | Lower-right corner |

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

| Property | Default | Description | |----------|---------|-------------| | exitPerimeter | 1 | Project exit point onto shape perimeter. Set to 0 for absolute point. | | entryPerimeter | 1 | Project entry point onto shape perimeter. Set to 0 for absolute point. |

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

| Style Value | Path Shape | Use Case | |-------------|-----------|----------| | orthogonalEdgeStyle | Right-angle bends | Flowcharts, architecture diagrams | | elbowEdgeStyle | Single elbow (L/Z) | Simple two-segment routing | | entityRelationEdgeStyle | Fixed-length stubs | ER diagrams | | segmentEdgeStyle | User-defined segments | Manual layout control | | sideToSideEdgeStyle | Horizontal routing | Left-to-right flows | | topToBottomEdgeStyle | Vertical routing | Top-down hierarchies | | loopEdgeStyle | Self-referencing loop | State machines, recursive flows | | isometricEdgeStyle | 30-degree angles | Isometric diagrams | | (omitted) | Straight line | Direct point-to-point |

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

Edge Path Modifiers

| Property | Values | Default | Description | |----------|--------|---------|-------------| | curved | 0, 1 | 0 | Smooth curved path instead of sharp corners | | rounded | 0, 1 | 1 | Round edge corners (orthogonal edges) | | elbow | horizontal, vertical | — | Preferred bend direction for elbow edges | | orthogonalLoop | 0, 1 | 1 | Routing algorithm for self-loops | | noEdgeStyle | 0, 1 | 0 | Disable edge style entirely | | jettySize | auto, number | auto | Minimum first/last segment length | | sourceJettySize | number | — | Override jetty at source end | | targetJettySize | number | — | Override jetty at target end |

Perimeter Spacing

| Property | Values | Default | Description | |----------|--------|---------|-------------| | perimeterSpacing | number | 0 | Gap between endpoint and perimeter (both ends) | | sourcePerimeterSpacing | number | — | Gap at source end only | | targetPerimeterSpacing | number | — | Gap at target end only |

Line Crossings

| Property | Values | Default | Description | |----------|--------|---------|-------------| | jumpStyle | arc, gap, sharp | — | Visual style at line crossings | | jumpSize | number | 6 | Size of crossing marker in pixels |

Waypoints

Waypoints are intermediate routing points that the edge MUST pass through. They are defined as ` elements inside an `.

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

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

Waypoint Behavior Per Edge Style

| Edge Style | Waypoint Behavior | |------------|-------------------| | orthogonalEdgeStyle | Routes with right angles through each waypoint | | curved=1 | Waypoints become Bezier-like control points | | (no edgeStyle) | Straight-line segments: source -> wp1 -> wp2 -> target | | elbowEdgeStyle | First waypoint determines elbow bend location | | segmentEdgeStyle | Full manual control via waypoints |

Unconnected Edge Endpoints

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

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.

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

| Property | Values | Description | |----------|--------|-------------| | portConstraint | eastwest, northsouth, perimeter, fixed | Restrict connection directions | | sourcePortConstraint | direction | Constraint on source side only | | targetPortConstraint | direction | Constraint on target side only |

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 ``.

Label Positioning Rules

| Property | Range | Description | |----------|-------|-------------| | x | -1 to 1 | Position along edge path. -1 = at source, 0 = center, 1 = at target. | | y | pixels | Perpendicular offset. Positive = below/right, negative = above/left. |

Label at Center (Default)

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

Label at Custom Position

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:

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.

| Property | Values | Default | Description | |----------|--------|---------|-------------| | endArrow | classic, block, open, diamond, oval, none, ... | classic | Arrow at target end | | startArrow | same as endArrow | none | Arrow at source end | | endFill | 0, 1 | 1 | 1 = solid, 0 = hollow | | startFill | 0, 1 | 1 | 1 = solid, 0 = hollow | | endSize | number | — | Arrow size in pixels | | startSize | number | — | Arrow size in pixels |

Common UML Arrow Patterns

| Relationship | Style Fragment | |--------------|---------------| | Inheritance | endArrow=block;endFill=0; | | Composition | startArrow=diamond;startFill=1; | | Aggregation | startArrow=diamond;startFill=0; | | Dependency | endArrow=open;dashed=1; | | Implementation | endArrow=block;endFill=0;dashed=1; |

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 ``
• [ ] 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](references/methods.md) — Complete property reference for edges and connections
• [references/examples.md](references/examples.md) — Working XML examples for every connection pattern
• [references/anti-patterns.md](references/anti-patterns.md) — What NOT to do with connections

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Impertio-Studio
• Source: Impertio-Studio/Draw.io-Claude-Skill-Package
• License: MIT

Install and usage instructions live in the source repository linked above.