--- description: "Complete draw.io XML generation reference including mxGraphModel structure, cell types, style properties, and validation rules" triggers: - drawio - xml - mxgraph - mxcell - diagram xml - drawio xml globs: - "**/*.drawio" - "**/*.drawio.xml" - "**/*.drawio.svg" --- # draw.io XML Generation Reference ## XML Document Structure ### Full Format (mxfile wrapper) ```xml ``` ### Simplified Format (IMPORT ONLY — do NOT use for .drawio files) The `mxGraphModel`-only format works for clipboard import but **causes blank files** when saved directly as `.drawio`. The draw.io desktop app and web editor both expect the full `` wrapper to render the diagram. Always use the full format above. ```xml ``` ### mxGraphModel Attributes | Attribute | Default | Description | |-----------|---------|-------------| | `dx` | 0 | Horizontal scroll offset | | `dy` | 0 | Vertical scroll offset | | `grid` | 1 | Show grid (0/1) | | `gridSize` | 10 | Grid spacing in px | | `guides` | 1 | Enable alignment guides | | `tooltips` | 1 | Show tooltips | | `connect` | 1 | Enable connection points | | `arrows` | 1 | Show arrows on edges | | `fold` | 1 | Enable container folding | | `page` | 1 | Show page boundaries | | `pageScale` | 1 | Page zoom scale | | `pageWidth` | 1169 | Page width (A4 landscape) | | `pageHeight` | 827 | Page height (A4 landscape) | | `math` | 0 | Enable LaTeX math rendering | | `shadow` | 0 | Default shadow on shapes | | `background` | `none` | Background color — **always use `none` (transparent)** for clean embedding | **IMPORTANT**: Always set `background="none"` on the `` element. Transparent backgrounds ensure diagrams embed cleanly in any context (dark mode, light mode, wiki pages, PRs). Never use a solid white background unless explicitly requested. ## Mandatory Structural Cells Every diagram MUST begin with these two cells. They are never rendered but form the cell hierarchy root. ```xml ``` - `id="0"` is the absolute root. It has no parent. - `id="1"` is the default layer. All visible shapes/edges use `parent="1"` unless placed on a custom layer. - Omitting either cell causes diagram corruption. ## Vertex Cells (Shapes) Vertices represent boxes, circles, and all other shapes. They require `vertex="1"` and an `mxGeometry` child. ```xml ``` ### Vertex Attributes | Attribute | Required | Description | |-----------|----------|-------------| | `id` | Yes | Unique identifier (string) | | `value` | No | Label text (plain or HTML) | | `style` | No | Semicolon-delimited style string | | `vertex` | Yes | Must be `"1"` | | `parent` | Yes | Parent cell ID (usually `"1"`) | | `connectable` | No | `"0"` to disable connections | ### mxGeometry for Vertices ```xml ``` | Attribute | Description | |-----------|-------------| | `x` | Left edge position (px from canvas origin) | | `y` | Top edge position (px from canvas origin) | | `width` | Shape width in px | | `height` | Shape height in px | | `as` | Must be `"geometry"` | | `relative` | `"1"` for relative positioning inside parent | ## Edge Cells (Connectors) Edges connect vertices. They require `edge="1"` and typically `source`/`target` attributes. ```xml ``` ### Edge Attributes | Attribute | Required | Description | |-----------|----------|-------------| | `id` | Yes | Unique identifier | | `value` | No | Edge label | | `style` | No | Style string | | `edge` | Yes | Must be `"1"` | | `source` | No | Source vertex ID | | `target` | No | Target vertex ID | | `parent` | Yes | Parent cell ID | ### mxGeometry for Edges Edge geometry uses `relative="1"` and may contain waypoints: ```xml ``` - `sourcePoint` / `targetPoint`: fallback when source/target cells are not set. - `Array as="points"`: intermediate waypoints for routing. ### Edge Labels Position labels along edge using `mxGeometry` inside a child cell: ```xml ``` - `x` in [-1, 1]: position along edge (-1=source, 0=middle, 1=target). - `y`: perpendicular offset. ## Style String Format Styles are semicolon-separated `key=value` pairs. Order does not matter. A trailing semicolon is conventional. ``` rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=14; ``` Named styles can appear as the first token without `=`: ``` shape=hexagon;perimeter=hexagonPerimeter2;size=0.25; ``` ### Fill Properties | Property | Values | Description | |----------|--------|-------------| | `fillColor` | `#hex`, `none` | Shape fill color | | `gradientColor` | `#hex`, `none` | Gradient end color | | `gradientDirection` | `south`, `north`, `east`, `west` | Gradient direction | | `opacity` | 0-100 | Overall opacity | | `fillOpacity` | 0-100 | Fill-only opacity | | `glass` | 0/1 | Glass/gloss effect | | `shadow` | 0/1 | Drop shadow | | `swimlaneFillColor` | `#hex` | Swimlane body fill | ### Stroke Properties | Property | Values | Description | |----------|--------|-------------| | `strokeColor` | `#hex`, `none` | Border/line color | | `strokeWidth` | number | Border width in px | | `dashed` | 0/1 | Dashed line | | `dashPattern` | string | Dash pattern (e.g., `"8 4"`) | | `strokeOpacity` | 0-100 | Stroke-only opacity | | `fixDash` | 0/1 | Keep dash pattern on zoom | ### Shape Properties | Property | Values | Description | |----------|--------|-------------| | `shape` | shape name | Shape type (see Shape Types below) | | `rounded` | 0/1 | Round corners on rectangles | | `arcSize` | number | Corner radius (0-50) | | `perimeter` | perimeter name | Connection point calculation | | `aspect` | `fixed` | Lock aspect ratio | | `direction` | `south`, `north`, `east`, `west` | Shape rotation direction | | `rotation` | degrees | Rotation angle | | `flipH` | 0/1 | Flip horizontal | | `flipV` | 0/1 | Flip vertical | | `size` | number | Shape-specific size parameter | | `imageWidth`, `imageHeight` | number | Embedded image dimensions | | `image` | URL | Image source | ### Text Properties | Property | Values | Description | |----------|--------|-------------| | `fontSize` | number | Font size in pt | | `fontFamily` | string | Font name (e.g., `"Helvetica"`) | | `fontColor` | `#hex` | Text color | | `fontStyle` | bitmask | 0=normal, 1=bold, 2=italic, 4=underline (combine with +) | | `align` | `left`, `center`, `right` | Horizontal text alignment | | `verticalAlign` | `top`, `middle`, `bottom` | Vertical text alignment | | `labelPosition` | `left`, `center`, `right` | Label horizontal position relative to shape | | `verticalLabelPosition` | `top`, `middle`, `bottom` | Label vertical position | | `labelBackgroundColor` | `#hex`, `none` | Label background | | `labelBorderColor` | `#hex`, `none` | Label border | | `html` | 0/1 | Enable HTML label rendering | | `whiteSpace` | `wrap` | Enable text wrapping | | `overflow` | `fill`, `width`, `hidden`, `visible` | Text overflow behavior | | `spacing` | number | Padding around text | | `spacingTop`, `spacingBottom`, `spacingLeft`, `spacingRight` | number | Directional padding | | `textOpacity` | 0-100 | Text-only opacity | **fontStyle bitmask examples:** - `fontStyle=1` = bold - `fontStyle=2` = italic - `fontStyle=3` = bold + italic - `fontStyle=5` = bold + underline - `fontStyle=7` = bold + italic + underline ### Edge Properties | Property | Values | Description | |----------|--------|-------------| | `edgeStyle` | style name | Edge routing algorithm | | `curved` | 0/1 | Curved edges | | `rounded` | 0/1 | Rounded corners on orthogonal edges | | `jettySize` | `auto`, number | Orthogonal edge segment length | | `startArrow` | arrow name | Arrow at source end | | `endArrow` | arrow name | Arrow at target end | | `startSize` | number | Start arrow size | | `endSize` | number | End arrow size | | `startFill` | 0/1 | Fill start arrow (1=filled, 0=open) | | `endFill` | 0/1 | Fill end arrow | | `jumpStyle` | `arc`, `gap`, `sharp`, `line`, `none` | Line crossing style | | `jumpSize` | number | Jump/gap size | | `exitX`, `exitY` | 0-1 | Source connection point (relative) | | `entryX`, `entryY` | 0-1 | Target connection point (relative) | | `exitDx`, `exitDy` | number | Source connection offset | | `entryDx`, `entryDy` | number | Target connection offset | | `exitPerimeter` | 0/1 | Use perimeter for source | | `entryPerimeter` | 0/1 | Use perimeter for target | | `sourcePortConstraint` | `north`, `south`, `east`, `west` | Constrain source side | | `targetPortConstraint` | `north`, `south`, `east`, `west` | Constrain target side | ### Container Properties | Property | Values | Description | |----------|--------|-------------| | `container` | 0/1 | Cell is a container/group | | `collapsible` | 0/1 | Show collapse/expand button | | `swimlaneFillColor` | `#hex` | Body fill of swimlane | | `startSize` | number | Header height in swimlane | | `childLayout` | `stackLayout` | Auto-layout children | | `horizontalStack` | 0/1 | Stack direction | | `stackFill` | 0/1 | Children fill container width | | `stackSpacing` | number | Gap between stacked children | | `resizeParent` | 0/1 | Resize parent to fit children | | `resizeParentMax` | number | Max parent resize | ### Sketch Properties | Property | Values | Description | |----------|--------|-------------| | `sketch` | 0/1 | Hand-drawn/sketch appearance | | `comic` | 0/1 | Comic/casual style (same as sketch) | | `fillStyle` | `solid`, `hachure`, `cross-hatch`, `dots`, `zigzag`, `dashes` | Sketch fill pattern | | `hachureGap` | number | Gap between fill lines | | `hachureAngle` | number | Angle of fill lines | | `jiggle` | number | Hand-drawn jiggle amount (1-5) | | `curveFitting` | number | Curve smoothness | ### Behavior Properties | Property | Values | Description | |----------|--------|-------------| | `movable` | 0/1 | Can be moved | | `resizable` | 0/1 | Can be resized | | `rotatable` | 0/1 | Can be rotated | | `editable` | 0/1 | Label can be edited | | `deletable` | 0/1 | Can be deleted | | `connectable` | 0/1 | Can have connections | | `cloneable` | 0/1 | Can be cloned | | `pointerEvents` | 0/1 | Responds to mouse events | | `locked` | 0/1 | Locked in place | ## Shape Types ### Core Shapes These are built-in and do not require a `shape=` prefix when used as the default: | Shape | Style | Notes | |-------|-------|-------| | Rectangle | (default, no shape needed) | Default shape | | Rounded Rectangle | `rounded=1;` | | | Ellipse | `shape=ellipse;` or `ellipse;` | Also `perimeter=ellipsePerimeter;` | | Rhombus (Diamond) | `shape=rhombus;` or `rhombus;` | Decision shape | | Triangle | `shape=triangle;` | Points right by default | | Hexagon | `shape=hexagon;perimeter=hexagonPerimeter2;size=0.25;` | | | Cloud | `shape=cloud;` | | | Cylinder | `shape=cylinder3;whiteSpace=wrap;` | Database shape | | Circle | `ellipse;aspect=fixed;` | Fixed aspect ellipse | | Line | `shape=line;` | Horizontal separator | | Arrow | `shape=singleArrow;` or `shape=doubleArrow;` | | ### Extended Shapes | Shape | Style | |-------|-------| | Cube | `shape=cube;whiteSpace=wrap;` | | Isometric Cube | `shape=isoCube;isoAngle=15;` | | Document | `shape=document;` | | Folder | `shape=folder;tabWidth=50;tabHeight=14;tabPosition=left;` | | Card | `shape=card;size=18;` | | Tape | `shape=tape;` | | Note | `shape=note;size=15;` | | Process | `shape=process;` | | Step | `shape=step;size=0.2;perimeter=stepPerimeter;` | | Callout | `shape=callout;size=20;position=0.5;position2=0.5;base=20;` | | Parallelogram | `shape=parallelogram;perimeter=parallelogramPerimeter;size=0.2;` | | Trapezoid | `shape=trapezoid;perimeter=trapezoidPerimeter;size=0.4;` | | Cross | `shape=cross;size=0.2;` | | Star | `shape=mxgraph.basic.star;` | | Heart | `shape=mxgraph.basic.heart;` | | Delay | `shape=delay;` | | Display | `shape=display;` | | Data Storage | `shape=dataStorage;` | | Internal Storage | `shape=internalStorage;dx=20;dy=20;` | | Or | `shape=or;` | | And | `shape=mxgraph.electrical.logic_gates.and;` | | Manual Input | `shape=manualInput;size=15;` | | Manual Operation | `shape=manualOperation;size=15;` | | Predefined Process | `shape=process;whiteSpace=wrap;` | ### UML Shapes | Shape | Style | |-------|-------| | Actor | `shape=umlActor;verticalLabelPosition=bottom;` | | Boundary | `shape=umlBoundary;` | | Entity | `shape=umlEntity;` | | Control | `shape=umlControl;` | | Lifeline | `shape=umlLifeline;perimeter=lifelinePerimeter;` | | Activation | `points=[];` (narrow rectangle on lifeline) | | Frame | `shape=umlFrame;` | | Destroy | `shape=umlDestroy;` | | Package | `shape=folder;tabWidth=80;tabHeight=20;` | | Component | `shape=component;` | | Interface | `shape=providedRequiredInterface;` | | Class | See UML Class example below | ## Stencil Libraries External shape libraries accessed via `shape=mxgraph..`: | Library Prefix | Domain | |---------------|--------| | `mxgraph.flowchart.*` | Flowchart symbols | | `mxgraph.bpmn.*` | BPMN 2.0 elements | | `mxgraph.aws4.*` | AWS Architecture (v4) | | `mxgraph.azure.*` | Microsoft Azure icons | | `mxgraph.gcp2.*` | Google Cloud Platform | | `mxgraph.kubernetes.*` | Kubernetes resources | | `mxgraph.cisco.*` | Cisco network equipment | | `mxgraph.uml.*` | UML 2.x extended | | `mxgraph.er.*` | Entity-Relationship | | `mxgraph.basic.*` | Basic shapes | | `mxgraph.arrows2.*` | Arrow shapes | | `mxgraph.lean_mapping.*` | Value stream mapping | | `mxgraph.electrical.*` | Electrical engineering | | `mxgraph.floorplan.*` | Floor plans | | `mxgraph.ios.*` | iOS mockups | | `mxgraph.android.*` | Android mockups | | `mxgraph.mockup.*` | Web mockups | | `mxgraph.archimate3.*` | ArchiMate 3.0 | | `mxgraph.sysml.*` | SysML | | `mxgraph.eip.*` | Enterprise Integration Patterns | | `mxgraph.c4.*` | C4 model | ### Common AWS Shapes ``` shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.ec2 shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.s3 shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.lambda shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.rds shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.dynamodb shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.sqs shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.sns shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.api_gateway shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.cloudfront shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.vpc shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.region ``` ### Common Azure Shapes ``` shape=mxgraph.azure.app_service shape=mxgraph.azure.storage_blob shape=mxgraph.azure.azure_functions shape=mxgraph.azure.sql_database shape=mxgraph.azure.virtual_machine shape=mxgraph.azure.azure_active_directory shape=mxgraph.azure.key_vaults shape=mxgraph.azure.kubernetes_services ``` ### Common Kubernetes Shapes ``` shape=mxgraph.kubernetes.pod shape=mxgraph.kubernetes.svc shape=mxgraph.kubernetes.deploy shape=mxgraph.kubernetes.rs shape=mxgraph.kubernetes.ing shape=mxgraph.kubernetes.cm shape=mxgraph.kubernetes.secret shape=mxgraph.kubernetes.ns shape=mxgraph.kubernetes.node shape=mxgraph.kubernetes.vol shape=mxgraph.kubernetes.pv shape=mxgraph.kubernetes.pvc ``` ## Edge Routing Styles | Style | Description | |-------|-------------| | `edgeStyle=orthogonalEdgeStyle` | Right-angle routing (most common) | | `edgeStyle=segmentEdgeStyle` | Manual segment routing | | `edgeStyle=elbowEdgeStyle` | Single elbow bend | | `edgeStyle=entityRelationEdgeStyle` | ER diagram routing | | `edgeStyle=isometricEdgeStyle` | Isometric routing | | `edgeStyle=none` | Straight line (no routing) | | `curved=1` | Smooth curved connections | ### Recommended Edge Style (prevents ugly connections) Always use this as the base edge style for clean, professional connections: ``` edgeStyle=orthogonalEdgeStyle;rounded=1;jettySize=auto;orthogonalLoop=1; ``` **Why each property matters:** - `rounded=1` — rounds corners at bends instead of sharp right angles - `jettySize=auto` — automatically calculates segment length so edges don't overlap shapes - `orthogonalLoop=1` — prevents self-loop edges from collapsing **For edges between non-aligned shapes**, specify explicit connection points: ```xml ``` **Connection point reference (exitX/exitY and entryX/entryY):** - `(0, 0.5)` = left center - `(1, 0.5)` = right center - `(0.5, 0)` = top center - `(0.5, 1)` = bottom center **For crossing edges**, add jump style: ``` jumpStyle=arc;jumpSize=16; ``` **For primary/important flows**, increase stroke width: ``` strokeWidth=2; ``` **For return/response flows**, use dashed: ``` dashed=1;dashPattern=8 4; ``` ## Perimeter Types Perimeters determine where connection points sit on a shape: | Perimeter | For Shape | |-----------|-----------| | `perimeter=rectanglePerimeter` | Rectangle (default) | | `perimeter=ellipsePerimeter` | Ellipse, circle | | `perimeter=rhombusPerimeter` | Diamond | | `perimeter=trianglePerimeter` | Triangle | | `perimeter=hexagonPerimeter2` | Hexagon | | `perimeter=parallelogramPerimeter` | Parallelogram | | `perimeter=trapezoidPerimeter` | Trapezoid | | `perimeter=stepPerimeter` | Step/chevron | | `perimeter=lifelinePerimeter` | UML lifeline | | `perimeter=centerPerimeter` | Connect to center only | | `perimeter=calloutPerimeter` | Callout/speech bubble | ## Arrow Types Used with `startArrow` and `endArrow`: | Arrow | Appearance | |-------|-----------| | `classic` | Standard filled arrowhead | | `classicThin` | Thin filled arrowhead | | `block` | Filled block arrow | | `blockThin` | Thin block arrow | | `open` | Open (unfilled) arrowhead | | `openThin` | Thin open arrowhead | | `oval` | Filled circle | | `diamond` | Filled diamond | | `diamondThin` | Thin diamond | | `box` | Square | | `halfCircle` | Half circle | | `circle` | Circle (used with `endFill=0` for open) | | `cross` | X mark | | `dash` | Short perpendicular line | | `async` | Half arrowhead (async message) | | `ERone` | ER "one" notation | | `ERmandOne` | ER "mandatory one" notation | | `ERmany` | ER "many" notation | | `ERoneToMany` | ER "one to many" | | `ERzeroToMany` | ER "zero to many" | | `ERzeroToOne` | ER "zero to one" | | `none` | No arrow | ## Standard Color Palette ### Fill / Stroke Pairs (draw.io defaults) | Name | Fill | Stroke | |------|------|--------| | Blue | `#dae8fc` | `#6c8ebf` | | Green | `#d5e8d4` | `#82b366` | | Orange | `#ffe6cc` | `#d6b656` | | Yellow | `#fff2cc` | `#d6b656` | | Red | `#f8cecc` | `#b85450` | | Purple | `#e1d5e7` | `#9673a6` | | Gray | `#f5f5f5` | `#666666` | | Dark Blue | `#1ba1e2` | `#006eaf` | | White | `#ffffff` | `#000000` | | Dark | `#333333` | `#000000` | ### Status Colors | Status | Fill | Stroke | |--------|------|--------| | Healthy / Success | `#d5e8d4` | `#82b366` | | Warning | `#fff2cc` | `#d6b656` | | Error / Critical | `#f8cecc` | `#b85450` | | Info | `#dae8fc` | `#6c8ebf` | | Disabled | `#f5f5f5` | `#666666` | ## HTML Labels When `html=1` is in the style, the `value` attribute supports HTML: ```xml ``` Supported HTML tags: - ``, `` - bold - ``, `` - italic - `` - underline - `
` or `
` - line break - `` - font styling - ``, `` - superscript, subscript - `
` - horizontal rule - ``, ``, `
` - tables (for UML class boxes, etc.) - `