draw.io Documentation

The internationalization (i18n) resources for draw.io are stored as text files. The English file serves as the source of truth for all keys, while other language files provide the translations.

• dia.txt: The English source language file that defines all available keys.
• dia_{lang}.txt: Translation files for specific languages (e.g., dia_fr.txt for French, dia_ja.txt for Japanese).
• dia_i18n.txt: A key reference file used for i18n management.

The layout system supports several modes: JSON-based custom layout arrays, libavoid shorthands (e.g., orthogonalEdge), parallels (using mxParallelEdgeLayout), and ELK presets (e.g., elkLayered).

Key components include:

• Layout-spec resolver: EditorUi.resolveLayoutList handles all layout specifications.
• Live Layout Containers: Inserted via Insert > Layout, these use the JSON childLayout form to create containers that automatically re-run layouts on any internal changes.
• Run Last Layout: Replays the last used layout specification via Arrange > Layout > Run Last Layout (stored in ui.lastLayoutSpec).

draw.io consumes several native-JS ports provided as committed browser bundles. These bundles are exposed via the global scope and are used for specific layout and routing functionalities.

libavoid provides obstacle-avoiding orthogonal edge routing. It computes edge paths that route around vertices (obstacles) without moving the vertices themselves.

This version is a pure-JS bundle built from source using Emscripten (wasm2js). It is designed for high CSP compatibility and synchronous initialization, meaning it does not require 'unsafe-eval' or 'wasm-unsafe-eval' and does not require awaiting a Promise to access the API.

If building buttons manually instead of using CustomDialog, you must replicate the standard spacing to ensure visual consistency. The button row should have a 34px top margin, and the content wrapper should have a 10px bottom padding.

// Content wrapper needs padding-bottom to prevent margin collapse
div.style.paddingBottom = '10px';

// Button row
var btns = document.createElement('div');
btns.style.marginTop = '34px';
btns.style.textAlign = 'right';

The official collection of Docker images and docker-compose configurations for draw.io is maintained in a separate repository: jgraph/docker-drawio. This repository provides several deployment options:

• draw.io docker image: Always kept up-to-date with current draw.io releases.
• draw.io export server image: Enables exporting draw.io diagrams to PDF and various image formats.
• Integrated deployments via docker-compose:
  • draw.io with the export server.
  • draw.io integrated within Nextcloud.
  • draw.io with PlantUML support.
  • A self-contained draw.io instance (includes export server, PlantUML, Google Drive support, OneDrive support, and EMF conversion for VSDX export) that does not depend on the draw.io website.

To ensure dialogs support both light and dark modes, do not hardcode hex or RGB color values in JavaScript. Instead, use CSS classes that leverage the light-dark() function.

Colors should be sourced from the theme palette variables defined in styles/grapheditor.css. Referencing these variables ensures that user color schemes (applied via the css configuration property) are respected. Using literal colors will cause components to opt out of theming.

Commonly used variables include:

• --strong-text-color
• --field-color
• --field-border-color
• --focus-color

To create alpha tints of an accent color, use the color-mix function with the focus color variable.

Mermaid can be triggered through several interfaces:

• Insert > Mermaid dialog: Provides a <select> to choose between mermaid (Diagram) and mermaidImage (Image) types.
• Double-click edit: The editMermaidData function uses a SimpleTextareaDialog with a headerControl parameter to allow switching between Diagram and Image representations.
• Embed descriptor: Use image:true as a peer to wrap.
• URL Hash: Use value.image:true with create= to trigger App.executeCreateObject.
• Desktop CLI: Use the --mermaid-image 1 flag to open .mmd or .mermaid files directly as images.

Group related controls in rounded section containers using the geDialogSection class.

Important Spacing Rules:

• Do not add per-row margin-top; spacing is handled centrally in grapheditor.css with a uniform 6px gap between rows.
• Always wrap controls in a proper row class (like geDialogFormRow or geDialogCheckRow) to ensure consistent min-height: 28px.
• If a row needs to be hidden conditionally, remove it from the DOM entirely (parentNode.removeChild) instead of using display:none to avoid breaking the :first-child CSS reset.

var section = document.createElement('div');
section.className = 'geDialogSection';
// ... add rows to section ...
div.appendChild(section);

The libavoid port provides obstacle-avoiding orthogonal edge routing. Unlike node layouts, it does not move vertices; it only re-routes edges around vertices acting as obstacles.

There are two main layers:

1. Canonical Core (js/libavoid-js/libavoid-routing.js): A model-free, pure-JS core accessible via globalThis.AvoidRouting. It contains computeRoutes and geometry helpers like constraintForPoint, jettyStub, filterEnclosing, dirForPoint, and clamp01. Tuning the algorithm should be done here.
2. Editor Binding (diagramly/LibavoidRouting.js): A thin wrapper for the draw.io editor that handles model access, events, previews, and styles. It injects defaults like LibavoidRouting.shapeBufferDistance and LibavoidRouting.idealNudgingDistance into the core.