Master reference for the Draw.io / mxGraph style system. Covers style string syntax, property categories, color system, fontStyle bitfield, perimeter matching, and style inheritance.
1. Style String Syntax
Every mxCell carries its appearance in a single style attribute: a semicolon-delimited
string of key=value pairs.
Format Rules
| Rule | Detail |
|---|---|
| Separator | Semicolon (;) between every property |
| Pair format | key=value (camelCase keys, no spaces around =) |
| Leading shape | A bare word WITHOUT = sets the base shape (e.g., ellipse;) |
| Trailing semicolon | ALWAYS terminate with ; |
| Booleans | ALWAYS 0 or 1 — NEVER true / false |
| Colors | #RRGGBB hex, none (transparent), or default (theme color) |
Leading Shape Identifier
When a style string starts with a bare word (no =), it sets the shape. These two are equivalent:
ellipse;whiteSpace=wrap;html=1;
shape=ellipse;whiteSpace=wrap;html=1;
Common leading identifiers: ellipse, rhombus, triangle, hexagon, swimlane,
image, line, text.
Mandatory Properties
Every AI-generated cell MUST include:
| Property | Why |
|---|---|
html=1 |
Enables HTML label rendering. Without it, labels lose all formatting. |
whiteSpace=wrap |
Enables word wrapping. Without it, long labels overflow shape bounds. |
2. Property Categories Overview
The style system has 120+ properties across these categories. Full details are in references/methods.md.
| Category | Key Properties | Applies To |
|---|---|---|
| Fill | fillColor, gradientColor, opacity, fillOpacity |
Vertices |
| Stroke | strokeColor, strokeWidth, dashed, dashPattern |
Both |
| Text | fontSize, fontFamily, fontColor, fontStyle, align |
Both |
| Shape | shape, perimeter, rounded, arcSize, rotation |
Vertices |
| Edge | edgeStyle, curved, startArrow, endArrow |
Edges |
| Container | container, collapsible, startSize, childLayout |
Vertices |
| Behavior | movable, resizable, editable, deletable |
Both |
Vertex-Only vs Edge-Only Properties
NEVER apply vertex properties to edges or vice versa — they are silently ignored.
- Vertex-only:
fillColor,shape(exceptconnector),container,collapsible,swimlane - Edge-only:
edgeStyle,startArrow,endArrow,curved,jettySize,exitX/Y,entryX/Y
3. Color System
Valid Color Formats
| Format | Example | Use |
|---|---|---|
#RRGGBB |
#DAE8FC |
Specific hex color |
none |
fillColor=none |
Transparent / no color |
default |
strokeColor=default |
Theme-dependent default |
NEVER use:
- RGB function syntax (
rgb(0,0,0)) - Short hex (
#FFF) - Named CSS colors (
red,blue) — use#FF0000,#0000FF
Color Properties
| Property | Applies To | Default |
|---|---|---|
fillColor |
Vertex interior | default (theme white) |
strokeColor |
Border / edge line | default (theme black) |
fontColor |
Label text | default (theme black) |
gradientColor |
Gradient end color | none |
labelBackgroundColor |
Label background | none |
labelBorderColor |
Label border | none |
swimlaneFillColor |
Swimlane body fill | — |
4. fontStyle Bitfield
The fontStyle property uses a bitmask to combine text decorations in a single integer.
Flags
| Flag | Value | Effect |
|---|---|---|
| Bold | 1 |
Bold text |
| Italic | 2 |
Italic text |
| Underline | 4 |
Underlined text |
| Strikethrough | 8 |
Strikethrough text |
Combining Flags
Add flag values together. NEVER use bitwise operators in the style string — use the pre-computed sum.
| fontStyle | Result |
|---|---|
0 |
Normal |
1 |
Bold |
2 |
Italic |
3 |
Bold + Italic |
4 |
Underline |
5 |
Bold + Underline |
7 |
Bold + Italic + Underline |
9 |
Bold + Strikethrough |
Decision Tree: fontStyle Value
Need bold?
YES → start with 1
NO → start with 0
Need italic?
YES → add 2
Need underline?
YES → add 4
Need strikethrough?
YES → add 8
Sum = fontStyle value
5. Perimeter System
The perimeter determines WHERE edges connect to a shape's boundary. A mismatched perimeter causes edges to float away from the shape outline.
Perimeter-Shape Matching (MANDATORY)
| Shape | REQUIRED Perimeter |
|---|---|
| Rectangle (default) | rectanglePerimeter (default — omit if rectangle) |
| Rounded rectangle | rectanglePerimeter |
| Ellipse / Circle | ellipsePerimeter |
| Double Ellipse | ellipsePerimeter |
| Rhombus / Diamond | rhombusPerimeter |
| Triangle | trianglePerimeter |
| Hexagon | hexagonPerimeter |
| Cloud | ellipsePerimeter |
| Cylinder | rectanglePerimeter |
| Swimlane | rectanglePerimeter |
| Parallelogram | rectanglePerimeter |
| Stencil (round) | ellipsePerimeter |
| Stencil (rectangular) | rectanglePerimeter |
Decision Tree: Which Perimeter?
Is the shape visually round/oval?
YES → perimeter=ellipsePerimeter
NO →
Is it a diamond/rhombus?
YES → perimeter=rhombusPerimeter
NO →
Is it a triangle?
YES → perimeter=trianglePerimeter
NO →
Is it a hexagon?
YES → perimeter=hexagonPerimeter
NO → perimeter=rectanglePerimeter (or omit — it is the default)
What Happens With Wrong Perimeters
- Ellipse + rectanglePerimeter: Edges connect at bounding box corners instead of the curved boundary. Visible gaps appear.
- Rectangle + ellipsePerimeter: Edges float outside or inside the rectangle.
- Rhombus + rectanglePerimeter: Edges connect to the bounding box, not the diamond edges. Gaps appear at the sides.
6. Style Inheritance and Defaults
Resolution Order (later overrides earlier)
- Built-in defaults (hardcoded in mxGraph)
- Theme defaults (from the stylesheet registered in the graph)
- Named style (if the style string references a registered name)
- Inline properties (explicit key=value pairs in the style string)
Vertex Defaults
shape=rectangle;perimeter=rectanglePerimeter;whiteSpace=wrap;html=1;
overflow=hidden;fillColor=#ffffff;strokeColor=#000000;fontColor=#000000;
fontSize=12;fontFamily=Helvetica;align=center;verticalAlign=middle;
Edge Defaults
shape=connector;endArrow=classic;html=1;strokeColor=#000000;fontColor=#000000;
fontSize=12;fontFamily=Helvetica;align=center;verticalAlign=middle;rounded=1;
You only need to specify properties that DIFFER from the defaults. A basic rectangle
needs only whiteSpace=wrap;html=1; because shape and perimeter are already defaults.
7. Quick-Reference Templates
Shapes
// Rectangle
rounded=0;whiteSpace=wrap;html=1;
// Rounded Rectangle
rounded=1;whiteSpace=wrap;html=1;arcSize=10;
// Ellipse
ellipse;whiteSpace=wrap;html=1;perimeter=ellipsePerimeter;
// Diamond
rhombus;whiteSpace=wrap;html=1;perimeter=rhombusPerimeter;
// Triangle
triangle;whiteSpace=wrap;html=1;perimeter=trianglePerimeter;
// Hexagon
shape=hexagon;whiteSpace=wrap;html=1;perimeter=hexagonPerimeter;
// Cylinder (Database)
shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;size=15;
// Swimlane
swimlane;horizontal=1;startSize=30;fillColor=#f5f5f5;strokeColor=#666666;fontStyle=1;container=1;collapsible=0;html=1;whiteSpace=wrap;
Edges
// Standard arrow
endArrow=classic;html=1;
// Orthogonal connector
edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;
// Dashed dependency
endArrow=open;dashed=1;html=1;
// Bidirectional
startArrow=classic;endArrow=classic;html=1;
// No arrows
endArrow=none;startArrow=none;html=1;
// UML inheritance (hollow triangle)
endArrow=block;endFill=0;html=1;edgeStyle=orthogonalEdgeStyle;
// UML composition (filled diamond)
startArrow=diamond;startFill=1;endArrow=open;html=1;
8. Critical Rules Summary
| # | Rule |
|---|---|
| 1 | ALWAYS include html=1 in every cell style |
| 2 | ALWAYS include whiteSpace=wrap for shapes with text labels |
| 3 | ALWAYS set perimeter matching the shape type (see Section 5) |
| 4 | ALWAYS terminate style strings with a semicolon |
| 5 | ALWAYS use 0/1 for booleans — NEVER true/false |
| 6 | ALWAYS use #RRGGBB hex for colors — NEVER short hex or named colors |
| 7 | NEVER apply vertex-only properties to edges or vice versa |
| 8 | ALWAYS set container=1 on shapes that hold children |
| 9 | ALWAYS set relative="1" on edge mxGeometry elements |
| 10 | ALWAYS pair labelPosition with opposite align value |
References
- references/methods.md — Complete property reference by category
- references/examples.md — Working XML examples for every style scenario
- references/anti-patterns.md — Common mistakes with explanations and fixes