vscode-drawio: Edit Draw.io Diagrams Directly Inside VS Code

What vscode-drawio Does and What Problem It Removes

Draw.io (also known as diagrams.net) is a browser-based diagram editor. Without this extension, editing a .drawio file in a project means leaving VS Code, opening a browser tab, making the change, exporting the file, and replacing the version in the repository. That cycle breaks the workflow for engineers who keep their diagrams close to their code.

vscode-drawio brings the Draw.io editor inside VS Code as a custom editor for diagram files. Opening a .drawio, .dio, .drawio.svg, or .drawio.png file triggers the Draw.io editor panel rather than showing raw XML. The change is saved back to the file automatically on each edit, the same way any other VS Code editor works.

The extension is mentioned in the official diagrams.net blog as an integration. It bundles an offline version of Draw.io by default, so diagram editing works without a network connection.

Creating a new diagram requires only creating an empty file with one of the supported extensions. There is no separate create dialog.

File Formats: .drawio, .drawio.svg, and .drawio.png

The extension handles four file types. Each has a different storage model:

.drawio and .dio files store the diagram as plain XML. These are the most git-friendly format because XML diffs legibly in version control. When two team members edit a .drawio file concurrently, the merge conflict is in XML, which a developer can read and resolve.

.drawio.svg files are valid SVG images that contain the Draw.io diagram embedded in SVG metadata. The README notes these can be embedded directly in GitHub README files without any export step. When the diagram is saved, the SVG portion is regenerated from the embedded diagram data, keeping both representations in sync.

.drawio.png files are valid PNG images with the diagram embedded in the PNG metadata. The README recommends SVG over PNG when possible because SVG scales without loss and produces smaller diffs.

A conversion command moves between formats without re-creating the diagram from scratch. In VS Code: open the command palette and use Draw.io: Convert To... to switch between .drawio, .drawio.svg, and .drawio.png.

The README makes a practical point about .drawio files and AI tooling: the file is a visual diagram for a human reviewer and plain XML for an AI agent. When an agent edits the XML in a pull request, the change appears in the open diagram panel immediately.

Installing the Extension and Opening a First Diagram

The extension is published to the VS Code Marketplace under the identifier hediet.vscode-drawio. The current version documented in package.json is 1.12.0. It requires VS Code 1.70.0 or later, and it works in both the desktop and the browser-based (web) version of VS Code.

To install from the marketplace, search for Draw.io Integration in the Extensions panel or navigate to the Marketplace page at the URL documented in the README.

To associate .svg files (not just .drawio.svg) with the Draw.io editor, add the following to VS Code settings.json:

"workbench.editorAssociations": {
    "*.svg": "hediet.vscode-drawio-text"
}

The README includes a caveat: this only works for SVG files created with Draw.io or the extension. Generic SVG files will not open meaningfully.

To open the XML view of a diagram alongside the visual editor, use the VS Code command View: Reopen Editor With... and choose the text editor. Both editors for the same file can be open simultaneously and stay synchronized. This is useful for find-and-replace operations on node labels or for reviewing what an AI agent changed in the diagram.

Liveshare Collaboration and the Simultaneous Edit Limitation

VS Code Liveshare allows multiple developers to edit files in the same session from different machines. Version 1.0 of this extension added support for collaborative diagram editing through Liveshare: participants see each other's cursor and selection inside the Draw.io panel in real time.

The README describes this as useful for discussing, reviewing, or brainstorming diagrams. With Draw.io's freehand drawing tool and LaTeX support in node labels, the extension can serve as a whiteboard tool for remote code interviews.

There is a documented limitation to be aware of: the extension synchronizes the Draw.io diagram through a shared text document that Liveshare hosts. Liveshare does not understand the Draw.io XML structure, only that it is text. If two participants make changes simultaneously, modification conflicts can occur at the text level. The README states this explicitly. Sequential editing is safe; truly concurrent edits to the same diagram element carry a conflict risk.

Liveshare is a Microsoft product bundled with VS Code and available at no cost for the collaboration feature.

Code Link Feature: Jumping from a Diagram Node to Source

The code link feature connects diagram nodes to source code symbols. When enabled from the status bar, double-clicking a node whose label starts with # triggers a workspace symbol search for the rest of the label. A node labeled #MyClass jumps to the definition of MyClass if it exists anywhere in the open project.

The README documents one constraint: at least one file from the project containing the symbol must be open before VS Code's symbol index covers that project. The file itself does not need to contain the symbol; having any file from the project open is enough to include the project in the search scope.

The README also suggests keeping the diagram in the second editor column while navigating to symbols, so the diagram stays visible while the code file opens in the first column.

This feature became freely available after the author's GitHub sponsor threshold was reached, as the README notes.

Inline Diagrams in VS Code's Experimental Markdown Editor

VS Code Insiders (the pre-release build) ships an experimental Markdown WYSIWYG editor. In that editor, fenced code blocks tagged with drawio are rendered as live, resizable Draw.io editors inline in the Markdown:

`

drawio <mxfile>...</mxfile>

`

Edits write back directly to the fenced block in the Markdown file. The Markdown file is the single source of truth. Undo and redo, dirty state tracking, and hot exit all work as expected.

The block supports attributes: locked makes the diagram read-only inside the Markdown editor, and height=N fixes the display height:

drawio locked height=300 ```

This feature has specific restrictions. The VS Code contribution point for dynamic providers only exists in Insiders builds; stable VS Code shows the fence as text or renders it with a preview plugin. Dynamic providers also only run in trusted workspaces. Draw.io plugins are not loaded inside the inline editors.

Settings baked into the Draw.io editor, including theme, custom libraries, and fonts, apply the next time the Markdown editor is opened, not immediately.

Limitations, License, and Relation to the Official Draw.io Product

This is an unofficial extension. The README states this clearly and distinguishes it from Draw.io's own product. It is not maintained by the diagrams.net team or Atlassian (which acquired Lucidchart's main competitor, not diagrams.net). The extension relies on Draw.io's embedding API to render the editor inside VS Code.

The GPL-3.0 license applies to the extension code in the repository. The bundled Draw.io library has its own license from the diagrams.net project. Using the extension for diagram editing does not impose the GPL on project files that happen to be opened alongside diagrams.

The Draw.io application from Atlassian's ecosystem is the conventional comparison. diagrams.net (the web-based version) is free to use without an account. The Confluence and Jira integrations are commercial. vscode-drawio brings the same diagram editor into a code editor workflow without requiring a separate application or a Confluence subscription for diagram creation. The difference is collaboration model: vscode-drawio uses Liveshare, which is session-based and tied to VS Code. diagrams.net's own hosted version has persistent sharing through links and is accessible from any browser.

The last push to the repository was on 2026-09-26. The extension is at version 1.12.0.

Editorial conclusion

vscode-drawio is a practical choice for engineers who create architecture diagrams, system diagrams, or flow charts alongside their code and want those files to behave like code: version-controllable, diffable, and editable without leaving the editor. The .drawio.svg format is the highest-fidelity option because the file is a valid SVG for embedding in documentation while remaining editable in the Draw.io interface. The code link feature is limited by a requirement to have at least one project file open before the symbol search works. The inline Markdown diagram editor is limited to VS Code Insiders and trusted workspaces. This is an unofficial extension and is not developed by Diagrams.net or Atlassian; the GPL-3.0 license applies to the extension code itself, not to the Draw.io library it bundles.

Frequently asked questions

Official sources

1. hediet/vscode-drawio on GitHub
2. Issues
3. License: GPL-3.0
4. Project website
5. README