Draw.io AI Kit — API Cheat Sheet (Agent Reference)
This page is the whole engine API. Import drawio-ai-kit, but never read its files (or src/) — everything you need is here.
1. Imports
drawio-ai scaffold writes these for you. Writing a script by hand? Everything comes from ONE package. Run the script with drawio-ai run build.mjs
(it resolves drawio-ai-kit to the installed CLI, so no node_modules is needed):
import { writeFileSync } from "node:fs";
import { Diagram, group, frame, grid, icon, box, phantom, renderTree, stage, band, subnet, endpoint, ossBox } from "drawio-ai-kit";
// BPMN creators come from the same package:
import { pool, start, end, gateway, userTask, serviceTask, task } from "drawio-ai-kit";
Finding icon names
drawio-ai search "a, b, c" returns real catalog names. Comma or space separated (comma form returns an object keyed per keyword; space form returns one merged list); abbreviations (k8s, pg, es), plurals and small typos work; add aws/azure/gcp to scope. Pass the returned name to icon(id, name, label).
2. Layout Elements
Build node trees declaratively. No hardcoded coordinates.
Leaf Nodes
icon(id, name, label, opts): Draws a catalog icon.name: Catalog name (e.g.,"s3","databricks").label: Display text below the icon.
box(id, label, opts): Auto-sized text box. Width/height are computed from text length unless overridden inopts: { w, h }.endpoint(id, label, opts): Source/consumer card (entry/exit point, styled blue frame).ossBox(id, label, opts): Plain open-source/component box (white fill, neutral border).
Containers (Frames & Groups)
frame(id, label, opts, children): White frame with colored border and header text.opts: { dir: "col"|"row", gap: 12, stroke: "#HEX", fill: "#HEX", align: "center"|"left"|"right" }
group(id, gname, label, opts, children): Native cloud group container (e.g., VPC, Region, Subnet).gname:"group_region"|"group_vpc"|"group_subnet"|"group_account"|"group_availability_zone".opts: { dir: "col"|"row", gap, fill, stroke, priv: true|false, stack: N }stack: Ndraws the frame as N offset cards (multiplicity) — the AWS idiom for N identical copies (Dev/Test/Prod accounts, mirrored regions). Draw ONE structure, label it once; NEVER nest environments (nesting means containment). Use peer frames only when the environments genuinely differ.
grid(id, gname, label, opts, children): The packing primitive — lays children intocolscolumns of equal cells. Use it for every functional area (3–8 icons per box) instead of one frame per icon.opts: { cols: 3, gap: 14, pad: 12, fill, stroke }- Pick
colsto balance siblings. Frames side by side share a bottom edge only while their heights are close (the engine stops equalising past ~200px of stretch, so a far-shorter box hugs its content rather than becoming a white hole). For a level row, choosecolsper box soceil(n/cols)(the row count) comes out close across siblings — 5 icons atcols:2= 3 rows sits level with a 2-row neighbour.
stage(id, i, label, children, opts): Pipeline stage column.iis 0-based index (applies pale per-stage border color).band(id, label, children, opts): Cross-cutting row band (governance/security/ops).subnet(id, label, children, opts): AWS/Cloud subnet container. Border green if label contains"Public", teal if"Private".phantom(id, label, opts, children): Invisible layout container used to group columns/rows without rendering a boundary.
3. Diagram Builder
const d = new Diagram(type, opts): Initializes a diagram.type:"pipeline"|"hierarchy"|"network"|"hubspoke"|"hybrid"|"mesh"|"sequence".
renderTree(d, rootNode, [x, y]): Computes layout, places elements, and emits cells into diagramdstarting at[x, y](default:[40, 70]).d.link(srcId, tgtId, label, opts): Connects two nodes.- Default to a bare
d.link(src, tgt)with no routing opts — the router picks the facing side and port itself (it “attacks” the nearest side: a target to the left is entered on its left, a node below on its top) and de-collides parallels. Add a routing opt only after a render shows a plain link failing. opts: { flow: true }: Animated flow (main pipeline path).opts: { dash: true }: Dashed line (sync/DR/governance/lineage).opts: { role: "fanout" }: Sharp, bundled comb routing for 1-to-N fan-out.opts: { dir: "LR"|"TB" }: Force horizontal-first / vertical-first exit — only when the auto side is wrong.opts: { rounded: true }: Rounded corners (BPMN sequence flow, flow edges).opts: { route: { es: "R", en: "L" } }: Pin exit/entry sides (L/R/T/B). Last resort — it usually moves crowding elsewhere.opts: { rail: "top"|"bottom", lane }: ONLY for a long edge that would cut through the dense middle (a feedback edge across many columns). NOT for a short feedback between nodes at a similar level — a plain link connects them side-to-side, which is tidier than dropping to a gutter and looping.
- Default to a bare
d.clusterBox(id, childIds, label, opts): Draws a dashed, no-fill frame spanning multiple children afterrenderTree.opts: { icon, stroke, dashed: true, pad, padTop }
d.validate(): Audits diagram rules. Returns{ ok, errors, warnings, audit: { advice } }.d.link(a, b, label, { step: 1 }): Numbered badge on the edge (request walkthroughs, type"sequence").badgePos: -1…1slides the badge/label toward the source (-1) or target (1) when it lands on a caption.d.title(text): Page title, centered over the diagram.d.mxfile(title): Returns the raw XML string for saving:writeFileSync(path, d.mxfile("Title")).
4. BPMN (swimlanes)
Use new Diagram("bpmn") and ONE pool as the tree root. Every child carries { lane, col }
(0-based lane index, column index); the engine places it in that cell. phases are header labels
over the columns — each phase spans an even share of the columns (3 phases × 6 cols = 2 cols each).
BPMN links: pass { rounded: true } for sequence flow, { dash: true } for message flow between pools.
const proc = pool("order", "Order Management", { lanes: ["Customer", "Sales"], phases: ["Intake", "Review"] }, [
start("s1", { lane: 0, col: 0, label: "Order received" }),
userTask("t1", { lane: 0, col: 1, label: "Place order" }),
gateway("g1", { lane: 1, col: 2, label: "Approved?" }), // type: exclusive | parallel | inclusive | event
end("e1", { lane: 1, col: 3, label: "Done" }), // type: none | terminate | error | cancel
end("e2", { lane: 0, col: 3, label: "Rejected", type: "error" }),
]);
renderTree(d, proc);
d.link("s1", "t1"); d.link("t1", "g1"); d.link("g1", "e1", "yes"); d.link("g1", "e2", "no"); // a gateway must split or merge
- Creators:
start·intermediate·end·gateway·task·userTask·serviceTask·manualTask·scriptTask·businessRuleTask·subProcess. pool(..., { orientation: "vertical" })for vertical swimlanes.
5. Design Rules & Themes
- Theme Colors: Coral =
"#FF3621", Navy ="#1B3139", VPC ="#8C4FFF", Store ="#B0752A". - Nesting Hierarchy: Group levels are Cloud/Account/Region (0) → VPC (2) → AZ (3) → Subnet (4) → SG (5).
- Recoloring Policy: Never change catalog icon colors. Let the icons carry the color, keep frame backgrounds pale white (
light-dark(#ffffff, #0f1620)).