Drawio Syntax Cells

Draw.io Syntax: Cells

Purpose

This skill teaches how to create and configure every type of mxCell in Draw.io XML: vertex cells (shapes, images, containers), edge cells (connectors), UserObject/object wrappers for metadata, HTML labels, placeholder variables, groups, and container nesting.

Critical Rules (Memorize These)

1. ALWAYS set vertex="1" on shapes. Without it, the cell is invisible.
2. ALWAYS set edge="1" on connectors. Without it, the cell renders as a shape, not a line.
3. NEVER set both vertex="1" and edge="1" on the same cell.
4. NEVER omit the parent attribute on any cell except id="0".
5. ALWAYS use `` wrapper when attaching custom metadata properties.
6. ALWAYS XML-escape HTML in value attributes: ` to >, & to &, " to "`.
7. ALWAYS include html=1 in style when labels contain HTML markup.
8. ALWAYS include whiteSpace=wrap in style on vertex cells with text labels.

Decision Tree: What Type of Cell?

Is this a shape, box, icon, image, or container?
  YES --> vertex="1" (Section 1)
         Does it hold child cells?
           YES --> Add container="1" to style (Section 5)
           NO  --> Standard vertex
Is this a line, arrow, or connector?
  YES --> edge="1" (Section 2)
Does this cell need custom metadata properties?
  YES --> Wrap in  (Section 3)
  NO  --> Use plain 
Does the label contain HTML formatting?
  YES --> XML-escape the HTML, add html=1 to style (Section 4)
  NO  --> Use plain text in value attribute

---

1. Vertex Cells (Shapes)

A vertex cell represents any shape: rectangle, circle, diamond, image, icon, or container.

Minimal Vertex

Required Attributes for Every Vertex

| Attribute | Value | Rule | |-----------|-------|------| | id | Unique string | ALWAYS unique across entire file | | vertex | "1" | ALWAYS set to "1" — NEVER omit | | parent | Cell ID | ALWAYS "1" (default layer) or a container/layer ID | | style | Style string | ALWAYS include html=1;whiteSpace=wrap; |

Optional Vertex Attributes

| Attribute | Values | Purpose | |-----------|--------|---------| | value | String | Display text (plain or XML-escaped HTML) | | connectable | "0" / "1" | "0" disables connections. Default: "1" | | visible | "0" / "1" | "0" hides cell. Default: "1" | | collapsed | "0" / "1" | "1" collapses a container. Default: "0" |

Vertex Geometry

ALWAYS include ` with as="geometry"` as a child of the vertex mxCell:

| Attribute | Meaning | |-----------|---------| | x | Horizontal position of top-left corner (pixels from canvas origin) | | y | Vertical position of top-left corner (0,0 = top-left; y increases downward) | | width | Shape width in pixels | | height | Shape height in pixels |

Inside a group/container: x and y are RELATIVE to the parent's top-left corner, NOT the canvas origin.

---

2. Edge Cells (Connectors)

An edge cell represents a line or arrow connecting two vertices.

Minimal Edge

Required Attributes for Every Edge

| Attribute | Value | Rule | |-----------|-------|------| | id | Unique string | ALWAYS unique across entire file | | edge | "1" | ALWAYS set to "1" — NEVER omit | | parent | Cell ID | ALWAYS "1" (default layer) or a layer/container ID |

Edge Connection Attributes

| Attribute | Required | Purpose | |-----------|----------|---------| | source | Recommended | ID of the source vertex. MUST reference an existing vertex. | | target | Recommended | ID of the target vertex. MUST reference an existing vertex. |

Decision Tree: Connected vs Floating Edge

Does the edge connect to existing shapes?
  YES --> Set source="" and target=""
         Do both vertices exist in the diagram?
           YES --> Valid connected edge
           NO  --> INVALID — will produce broken connector
  NO  --> Use sourcePoint/targetPoint in geometry (floating edge)

Floating Edge (No source/target)

When an edge is NOT connected to any vertex, define terminal points:

Edge Geometry

Edge geometry ALWAYS uses relative="1":

For label positioning on edges:

| Attribute | Range | Meaning | |-----------|-------|---------| | x | -1 to 1 | Position along edge: -1 = source, 0 = center, 1 = target | | y | Pixel value | Perpendicular offset from edge path |

Edge with Label Offset

Edge with Waypoints

Waypoints are absolute canvas coordinates contained in ``.

---

3. UserObject / object Wrapper (Custom Metadata)

To attach custom key-value properties to any cell, wrap the ` in an element. The tags and ` are functionally identical.

Decision Tree: Plain mxCell vs object Wrapper

Does the cell need ONLY a text label?
  YES --> Use plain 
Does the cell need a tooltip, hyperlink, or custom properties?
  YES --> Use  wrapper
Does the cell use %placeholder% substitution?
  YES --> Use  wrapper with placeholders="1"

object Wrapper Structure

Attribute Migration Rules

When using `` wrapper:

• id attribute ALWAYS moves from mxCell to ``
• label attribute on ` replaces value` on mxCell
• Inner ` NEVER has id or value` attributes
• Inner ` ALWAYS retains vertex/edge, parent (for edges: source, target), and style`

EXCEPTION: The parent attribute stays on the inner `, NOT on `.

Reserved object Attributes

| Attribute | Purpose | |-----------|---------| | id | Unique identifier (REQUIRED) | | label | Display text (replaces mxCell value) | | tooltip | Hover text shown in the editor | | link | URL or internal page link (data:page/id,) | | placeholders | "1" to enable %variable% substitution | | tags | Comma-separated tags for search/filter |

Custom Attributes

Any additional attribute on `` becomes a custom property visible in Draw.io's Edit Data dialog (Ctrl+M):

object Wrapper for Edges

Edges with metadata use the same pattern:

---

4. HTML Labels

Draw.io supports rich HTML content in cell labels when the style includes html=1.

Enabling HTML Labels

Two requirements MUST be met:

1. html=1 MUST be in the style string
2. ALL HTML in the value attribute MUST be XML-escaped

XML Escaping Rules

| Character | Escape Sequence | Example | |-----------|----------------|---------| | ` | > | (see above) | | & | & | AT&T | | " | " | style="color:red"` |

HTML Label Example

Supported HTML Tags

• Text formatting: `, , , , , , `
• Block elements: `, , `
• Lists: `, , `
• Tables: `, , , `
• Spans: `` with inline styles
• Font: ` with color, face, size`
• Links: ``

Inline CSS in HTML Labels

Use style attribute on HTML elements (XML-escaped):

value="<div style="text-align:left;font-size:14px;"><b>Title</b><br><span style="color:#999;">Subtitle</span></div>"

---

5. Groups and Containers

Container Cell

A container is a vertex whose style includes container="1". Child cells set their parent to the container's ID.

Group Cell

A group uses style="group" and acts as an invisible bounding box:

Container vs Group Decision Tree

Do you need a visible box around the children?
  YES --> Use container=1 in style with a value/label
  NO  --> Use style="group" (invisible bounding box)
Should children move when the parent moves?
  YES --> Both containers and groups provide this
Should the container be collapsible?
  YES --> Use swimlane style (container with title bar)

Collapsible Container (Swimlane)

When collapsed="1", the cell renders at the alternateBounds size (160x30). When expanded, it renders at the normal size (300x200).

Coordinate Rules for Children

• Child coordinates are ALWAYS RELATIVE to the parent's top-left corner
• x="0" y="0" inside a container means the container's own top-left
• For swimlanes: account for the title bar height (typically 26-30px)

---

6. Placeholders (%variable% Syntax)

Placeholders enable dynamic text substitution in labels and tooltips.

Enabling Placeholders

Set placeholders="1" on the `` wrapper:

Renders as: "Server: web-01 (10.0.1.10)"

Variable Resolution Order

Draw.io resolves %placeholder% by walking UP the containment hierarchy. First match wins:

1. Cell-level properties (attributes on ``)
2. Parent container properties
3. Ancestor containers (upward through nesting)
4. Layer-level properties
5. Root cell (id="0") properties
6. File-level variables (vars on ``)

If no match is found, the placeholder renders as blank text.

Predefined Placeholders

| Placeholder | Value | |-------------|-------| | %id% | Cell ID | | %width% | Cell width in pixels | | %height% | Cell height in pixels | | %date% | Current date | | %time% | Current time | | %timestamp% | Full timestamp | | %page% | Current page name | | %pagenumber% | Current page number | | %pagecount% | Total page count | | %filename% | File name |

Escaping Literal Percent Signs

Use %% to display a literal %:

Battery: 80%% charged  -->  renders as "Battery: 80% charged"

---

7. Layer Cells

Layers are mxCell elements with parent="0". The default layer is id="1".

Adding a Second Layer

Content cells reference the layer by setting parent to the layer's ID:

Layer Visibility

Layer Order

XML document order determines stacking: earlier layers render BEHIND later layers.

---

8. Validation Checklist

Before delivering any diagram, verify:

• [ ] Every shape has vertex="1"
• [ ] Every connector has edge="1"
• [ ] No cell has both vertex="1" and edge="1"
• [ ] Every cell (except id="0") has a valid parent attribute
• [ ] Every edge source/target references an existing vertex ID
• [ ] All HTML in value attributes is XML-escaped
• [ ] html=1 is present in style when labels contain HTML
• [ ] whiteSpace=wrap is present in style for vertices with text
• [ ] All cell IDs are unique across the entire file
• [ ] Container children use coordinates relative to the parent
• [ ] ` wrappers have id and label; inner mxCell has neither id nor value`

References

• [references/methods.md](references/methods.md) — Complete attribute reference for all cell types
• [references/examples.md](references/examples.md) — Working XML examples for every cell pattern
• [references/anti-patterns.md](references/anti-patterns.md) — What NOT to do, with explanations

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.