Excalidraw JSON Schema Reference

An .excalidraw file is a JSON object with the following top-level structure:

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [ ... ],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": null
  }
}

Element Types

Common Properties (All Elements)

All elements share these fields:

id: string (unique, e.g., "node-1")
x: number (x position)
y: number (y position)
width: number
height: number
angle: number (usually 0)
strokeColor: string (hex code, e.g., "#000000")
backgroundColor: string (hex code, e.g., "#transparent")
fillStyle: "hachure" | "cross-hatch" | "solid"
strokeWidth: number (1 or 2)
strokeStyle: "solid" | "dashed" | "dotted"
roughness: number (0-2, 1 is standard hand-drawn look)
opacity: number (100)
groupIds: []
roundness: { "type": 3 } (for rounded corners) or null
seed: number (random integer)
version: number (incrementing)
versionNonce: number (random integer)
isDeleted: false
boundElements: [{ "id": "arrow-id", "type": "arrow" }] (for connecting arrows)

1. Rectangle (Container/Box)

{
  "type": "rectangle",
  "label": { "text": "Label inside?" } // NOTE: Excalidraw uses separate "text" elements bound to containers usually, but simple rects just exist.
}

Note: To put text 'inside' a box, creating a separate "text" element is often safer/standard, centered on the rect.

2. Ellipse (Start/End nodes)

{
  "type": "ellipse"
}

3. Diamond (Decision)

{
  "type": "diamond"
}

4. Text (Labels)

{
  "type": "text",
  "text": "Actual content\nNew line",
  "fontSize": 20,
  "fontFamily": 1, // 1: Virgil (Hand), 2: Helvetica, 3: Cascadia
  "textAlign": "center", // "left", "center", "right"
  "verticalAlign": "middle"
}

5. Arrow (Connectors)

Arrows connect two elements.

{
  "type": "arrow",
  "points": [[0, 0], [100, 50]], // Relative points from x,y. [0,0] is the start.
  "startBinding": { "elementId": "node-1", "focus": 0.5, "gap": 1 },
  "endBinding": { "elementId": "node-2", "focus": 0.5, "gap": 1 }
}

Tip: If binding is too complex to calc, just placing start/end points near the center of nodes works visualy.

Layout Strategy (Mental Model)

For a "Why, What, How" tree:

Why (Root): Top or Left.
What (Children): Level 2.
How (Grandchildren): Level 3.

User Journey: Linear flow: Step 1 -> Arrow -> Step 2 -> Arrow -> Step 3.

2.5 KiB Raw Permalink Blame History