A draw.io file is XML in the format of mxGraph, the JavaScript diagram library that draw.io is built on. JGraph documents it for people who generate diagrams; some attributes below, marked “mxGraph”, are not in that documentation but are written by draw.io and read by mxGraph’s codec.
Elements
| Element | Inside | Attributes |
|---|---|---|
mxfile | root | vars: a JSON object of variables that labels use as %name%. draw.io also writes host, modified, agent, etag, version, type and, in older files, compressed and pages; readers do not need them. |
diagram | mxfile | One per page: id, name. Holds an mxGraphModel, or the compressed text of one. |
mxGraphModel | diagram, or root | Page settings, below. A bare mxGraphModel is also accepted as a whole file. |
root | mxGraphModel | None; holds the cells. |
mxCell | root, UserObject | A shape, connector, layer or the root cell, below. |
UserObject, object | root | Wraps an mxCell to give it data: id, label (the text, in place of value), placeholders="1" to let the label use %name%, tooltip, link, tags, and any other attribute as custom data. |
mxGeometry | mxCell | Position and size, below. |
mxPoint | mxGeometry, Array | x, y, and as: sourcePoint or targetPoint (loose connector ends) or offset (label offset). mxGraph. |
Array | mxGeometry | as="points": the waypoints of a connector, as mxPoints. mxGraph. |
mxGraphModel attributes
| Attribute | Meaning |
|---|---|
dx, dy | Scroll position of the view. |
grid, gridSize | Grid shown (0 or 1) and its spacing. |
guides | Alignment guides on (1) or off. |
tooltips | Tooltips on or off. |
connect | Connection arrows on hover on or off. |
arrows | Arrows on shapes for quick connecting. |
fold | Containers can be collapsed. |
page | Page view on (1) or an endless canvas (0). |
pageScale | Scale of the page. |
pageWidth, pageHeight | Page size in pixels, such as 827 by 1169 for A4 or 850 by 1100 for US Letter. |
background | Page background colour. mxGraph. |
math | Typeset LaTeX and AsciiMath in labels (1). |
shadow | Shadows on all shapes (1). |
adaptiveColors | How colours adapt in dark mode. |
mxCell attributes
| Attribute | Meaning |
|---|---|
id | Unique ID. Cell 0 is the root and cell 1 (parent 0) the default layer; every model starts with both. |
parent | ID of the layer, group or container the cell belongs to. A cell whose parent is 0 is a layer. |
value | The label: plain text, or XML-escaped HTML when the style has html=1. |
style | The style string, below. |
vertex | 1 for a shape. |
edge | 1 for a connector. A cell is a vertex or an edge, never both. |
source, target | For a connector, the IDs of the cells it joins. mxGraph. |
connectable | 0 if nothing may connect to it. mxGraph. |
collapsed | 1 if a container is folded. mxGraph. |
visible | 0 if hidden; used for hidden layers. mxGraph. |
mxGeometry attributes
| Attribute | Meaning |
|---|---|
x, y | Top-left corner. Inside a container they are relative to the container. |
width, height | Size. |
relative | 1 on connectors and on labels placed relative to their parent; x and y are then fractions. mxGraph. |
as | Always geometry. |
A connector still needs an mxGeometry element, usually
relative="1" with no size.
Compressed pages
When compression is on, the text of a diagram element is the page’s
mxGraphModel encoded in three steps, which a reader reverses:
encodeURIComponentof the XML;- raw Deflate, with no zlib header;
- Base64.
To read it: Base64-decode, inflate (raw), then URL-decode. Current versions of draw.io write uncompressed XML unless compression is turned on; older files are usually compressed.
Diagrams inside images
- .drawio.png: the
mxfileXML is stored, URL-encoded, in a PNG text chunk with the keywordmxfile. - .drawio.svg: the XML is in the
contentattribute of the rootsvgelement, XML-escaped.
Opening either file in draw.io restores the editable diagram.
Style strings
A style is a list of key=value; pairs. A word with no = is
the name of a predefined style class (such as text or
ellipse) whose keys apply first. Colours are #RRGGBB or one of
none, default (theme colour), inherit (the
parent’s), fillColor, strokeColor,
parentFillColor and parentStrokeColor; dark-mode colours use
light-dark().
Shape
| Key | Values | Meaning |
|---|---|---|
shape | rectangle, ellipse, rhombus, triangle, hexagon, cloud, cylinder, line, arrow, arrowConnector, doubleEllipse, image, label, swimlane, actor, connector, and stencils named mxgraph.… | The shape drawn. |
perimeter | rectanglePerimeter, ellipsePerimeter, rhombusPerimeter, trianglePerimeter, hexagonPerimeter2, parallelogramPerimeter, trapezoidPerimeter, calloutPerimeter, backbonePerimeter, centerPerimeter, stepPerimeter, cloudPerimeter | The outline connectors attach to. |
rounded, arcSize, absoluteArcSize | 0/1, number, 0/1 | Rounded corners and their radius (percent of the shorter side, or pixels). |
aspect | variable, fixed | Lock the proportions. |
direction | north, south, east, west | Turn in 90° steps. |
flipH, flipV, rotation | 0/1, 0/1, degrees | Mirror and rotate. |
fixedSize, roundedPerimeter | 0/1 | Size independent of the label; connectors end on the rounded outline. |
Fill, stroke and effects
| Key | Values | Meaning |
|---|---|---|
fillColor, gradientColor, gradientDirection | colour, colour, north/south/east/west | Fill and gradient. |
strokeColor, strokeWidth | colour, number | Outline. |
dashed, dashPattern | 0/1, lengths such as 8 8 | Dashed outline. |
opacity, fillOpacity, strokeOpacity, opacityGroup | 0 to 100, 0/1 | Transparency. |
glass, shadow | 0/1 | Glass highlight, drop shadow. |
multiple, multipleCount, multipleDx, multipleDy | 0/1, 1 to 10, numbers | Stacked copies behind the shape. |
sketch, comic, fillStyle, fillWeight, hachureGap, hachureAngle, jiggle, curveFitting, simplification, disableMultiStroke, disableMultiStrokeFill | fillStyle: solid, hachure, cross-hatch, dots | Hand-drawn look. |
Text and labels
| Key | Values | Meaning |
|---|---|---|
html, whiteSpace | 0/1, wrap/nowrap | HTML labels and wrapping. |
fontSize, fontFamily, fontColor | number, name, colour | Font. |
fontStyle | bit mask: 1 bold, 2 italic, 4 underline (added together) | Font style. |
align, verticalAlign | left/center/right, top/middle/bottom | Text alignment. |
labelPosition, verticalLabelPosition | as align, as verticalAlign | Label placed beside, above or below the shape. |
labelPerimeter, labelPlacement, labelWidth | 0/1, auto, number | Label outline, automatic placement, fixed width. |
labelBackgroundColor, defaultLabelBackgroundColor, labelBorderColor | colour, page, colour | Label box. |
overflow | visible, hidden, fill, width | Text overflow. |
spacing, spacingTop, spacingBottom, spacingLeft, spacingRight | numbers | Padding. |
textOpacity, textDirection, horizontal, inheritText | 0 to 100, default/ltr/rtl, 0/1, keys | Text opacity and direction, vertical text, connector label styles. |
Connectors
| Key | Values | Meaning |
|---|---|---|
edgeStyle | orthogonalEdgeStyle, segmentEdgeStyle, elbowEdgeStyle, entityRelationEdgeStyle, isometricEdgeStyle, loopEdgeStyle, sideToSideEdgeStyle, topToBottomEdgeStyle, none | Routing. |
curved, curveGeometry, labelOnCurve, elbow | 0/1, 0/1, 0/1, horizontal/vertical | Curves and elbow direction. |
jettySize, sourceJettySize, targetJettySize, orthogonalLoop | auto or number, 0/1 | Distance from the port before turning; self-loops. |
jumpStyle, jumpSize, jumpLayers | arc/gap/sharp/line, number, 0/1 | How crossing lines are drawn. |
followTerminals, libavoidRouting, libavoidSpacing, ties, tie, tieSpacing | Waypoints, obstacle-avoiding routing and ties. | |
exitX, exitY, exitDx, exitDy, exitPerimeter, entryX, entryY, entryDx, entryDy, entryPerimeter | 0 to 1, pixels, 0/1 | Fixed connection points on the source and target. |
sourcePerimeterSpacing, targetPerimeterSpacing, fixedPointSpacing, portConstraint | numbers, 0/1, eastwest/northsouth/perimeter/fixed | Gaps and allowed sides. |
startArrow, endArrow | none, classic, classicThin, block, blockThin, open, openThin, oval, diamond, diamondThin, box, halfCircle, circle, circlePlus, cross, baseDash, doubleBlock, dash, async, openAsync, manyOptional | Arrowheads; defaults none and classic. |
startSize, endSize, startFill, endFill, startFillColor, endFillColor, startStrokeColor, endStrokeColor | number, 0/1, colours | Arrowhead size, fill and colours. |
Containers, layout, images and behaviour
| Key | Meaning |
|---|---|
container, collapsible, recursiveResize, swimlaneFillColor, startSize | Containers and swimlanes (startSize is the header size here). |
childLayout | stackLayout, tableLayout, rack, circleLayout, flowLayout, treeLayout, organicLayout, or URL-encoded JSON. |
resizeParent, resizeParentMax, resizeLast, horizontalStack, stackSpacing, stackBorder, stackUnitSize, allowGaps, marginTop, marginRight, marginBottom, marginLeft | Stack layouts. |
rackUnitSize, horizontalRack | Rack layouts. |
flowOrientation, intraCellSpacing, interRankCellSpacing, interHierarchySpacing, parallelEdgeSpacing | Flow layouts. |
horizontalTree, treeLevelDistance, parentPadding | Tree layouts. |
image, imageWidth, imageHeight, imageAlign, imageVerticalAlign, imageAspect | Images in shapes; image is a URL or data URI. |
movable, resizable, rotatable, bendable, editable, deletable, cloneable, foldable, connectable, pointerEvents, autosize, collapsedPoints, newEdgeStyle | What the user may do with the cell. |
stylePlaceholders, styleRules | Placeholders in the style, and page style rules. |
Style classes
text, edgeLabel, label, icon,
swimlane, group, ellipse, rhombus,
triangle, line, image, arrow, the
colour themes blue, green, yellow,
orange, red, pink, purple,
gray, turquoise, and the same with plain- in
front for no shadow or glass.