draw.io

The entry point @tiptap-pro/extension-diagrams/drawio draws diagrams stored as draw.io XML, the format of the draw.io diagram editor, and connects that editor to change them. It draws no charts.
New tab

Quick start

The Renderer draws with the draw.io viewer, a script that is not on npm. Copy viewer-static.min.js from a draw.io release (src/main/webapp/js/ in the jgraph/drawio repository) into your app, and pass the URLs of both scripts:

import { Diagrams } from '@tiptap-pro/extension-diagrams'
import { drawioDiagramRenderer } from '@tiptap-pro/extension-diagrams/drawio'
import rendererUrl from '@tiptap-pro/extension-diagrams/drawio-renderer?url&no-inline'
import viewerUrl from './vendor/drawio/viewer-static.min.js?url'

Diagrams.configure({
  diagramRenderers: [drawioDiagramRenderer({ viewerUrl, rendererUrl })],
})

Install Diagrams has the complete editor around these lines. What a draw.io source is inserts a diagram.

Options

OptionTypeDefaultDescription
viewerUrlstringRequiredURL of viewer-static.min.js
rendererUrlstringRequiredURL of @tiptap-pro/extension-diagrams/drawio-renderer
scriptNoncestring | nullnullNonce for a nonce-based Content Security Policy
idstring'drawio'Names the Renderer
labelstring'draw.io'The name for a menu

Without either URL, a diagram shows the error "Set viewerUrl and rendererUrl to draw draw.io diagrams."

What a draw.io source is

A diagram with format: 'drawio' holds draw.io XML, an <mxfile> or a bare <mxGraphModel>:

editor.commands.insertFlowDiagram({ source: drawioXml, format: 'drawio', title: 'Order process' })

The document stores an <mxfile> with plain XML pages, so the stored text can be read and compared. A bare model becomes a file with one page, and a compressed page is uncompressed, or kept as it is when that fails. Pasting draw.io XML as text gives a draw.io diagram.

insertFlowDiagram and updateFlowDiagram return false for anything else, and for source over 1,000,000 characters. updateFlowDiagram({ source, format }) changes a diagram's format, such as a Mermaid diagram saved from the draw.io editor, with the new source in the same call.

How it draws

The draw.io viewer runs in one hidden iframe per web page, with sandbox="allow-scripts" and no network access. Renderers with a different viewerUrl, rendererUrl or scriptNonce get an iframe each. It loads with the first draw.io diagram, about 4.4 MB or 940 kB compressed. Drawing takes tens of milliseconds, and results are cached by source.

What the diagram looks like

A diagram keeps its own colors, because the --tt-flow-diagram-* custom properties do not reach it. It is drawn on its own background or on white, in the page's light or dark scheme where draw.io supports it.

  • HTML labels are drawn, but their links do nothing in the image.
  • Stencil shapes from AWS, Azure, Cisco and other libraries draw as empty boxes, because the sandbox cannot load their files.
  • Images in a diagram must be data: URLs.

In an export

In PNG, WebP, JPEG and Word exports, labels are plain text, without HTML bold, colors or line breaks. A draw.io diagram cannot be exported on a server, because the viewer lays out text in a browser.

Editing in the draw.io editor

Users change a draw.io diagram in the draw.io editor, in an iframe you build. connectDrawioEditor calls onSave with the XML on each save. This example opens the first draw.io diagram of editor, which must hold one, and writes each save back:

import { connectDrawioEditor, drawioEditorUrl } from '@tiptap-pro/extension-diagrams/drawio'

const diagram = editor.storage.diagrams.listDiagrams().find(item => item.format === 'drawio')

const dialog = document.createElement('dialog')
const frame = document.createElement('iframe')
frame.src = drawioEditorUrl() // https://embed.diagrams.net/?embed=1&proto=json…
dialog.append(frame)
document.body.append(dialog)
dialog.showModal()

const connection = connectDrawioEditor(frame, {
  source: diagram.source,
  title: diagram.title ?? undefined,
  onSave: source =>
    editor.commands.updateFlowDiagram({ pos: diagram.pos, source, format: 'drawio' }),
  onExit: () => dialog.close(),
})

// Escape closes the dialog too
dialog.onclose = () => {
  connection.destroy()
  dialog.remove()
}

The editor works on a copy, so a save replaces changes others made meanwhile.

drawioEditorUrl(options?)

Builds the editor URL in the JSON embed mode connectDrawioEditor speaks. params can override its parameters.

OptionTypeDefaultDescription
basestring'https://embed.diagrams.net/'The draw.io editor. Point it at your own copy to keep diagrams off a third-party origin
saveAndExitbooleantrueOffers Save and Exit next to Save
paramsRecord<string, string>NoneAdds editor URL parameters, such as lang

connectDrawioEditor(frame, options)

Opens a diagram in the editor in frame, and returns { destroy }, which stops listening and leaves the iframe to you. Messages go to and come only from the iframe's origin.

OptionTypeDefaultDescription
sourcestringNoneThe draw.io XML to open. Empty opens a blank page
mermaidstringNoneMermaid source to open instead. The editor converts it to draw.io shapes, and a subgraph to a swimlane
titlestringNoneShown in the editor's title bar
onSave(source, { exit })(source, { exit }) => voidRequiredCalled with the XML on Save, and with exit: true on Save and Exit
onExit()() => voidRequiredCalled when the editor closes, also after Save and Exit
onAutosave(source)(source) => voidNoneTurns on autosave, and is called with the XML after every change
onError(message)(message) => voidNoneCalled when the editor could not open the source, or sent something that is not draw.io XML

What onSave and onAutosave receive is normalized like any stored draw.io source, see What a draw.io source is.

From Mermaid to draw.io

Open a Mermaid diagram with the mermaid option and save it with format: 'drawio'. It becomes a draw.io diagram. You can go back to Mermaid only with undo.

Hosting the editor yourself

The draw.io editor is a static web app, published as the jgraph/drawio Docker image:

docker run --rm -p 8080:8080 jgraph/drawio
frame.src = drawioEditorUrl({ base: 'http://localhost:8080/' })

The embed protocol stays the same. The diagram then reaches no draw.io server, and editing works offline, except web fonts in labels and online shape libraries.

Serve the editor over HTTPS if your page uses HTTPS. Pin the image to a tag, and update it with the viewer you serve as viewerUrl, so both read the same XML.