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
| Option | Type | Default | Description |
|---|---|---|---|
viewerUrl | string | Required | URL of viewer-static.min.js |
rendererUrl | string | Required | URL of @tiptap-pro/extension-diagrams/drawio-renderer |
scriptNonce | string | null | null | Nonce for a nonce-based Content Security Policy |
id | string | 'drawio' | Names the Renderer |
label | string | '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.
| Option | Type | Default | Description |
|---|---|---|---|
base | string | 'https://embed.diagrams.net/' | The draw.io editor. Point it at your own copy to keep diagrams off a third-party origin |
saveAndExit | boolean | true | Offers Save and Exit next to Save |
params | Record<string, string> | None | Adds 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.
| Option | Type | Default | Description |
|---|---|---|---|
source | string | None | The draw.io XML to open. Empty opens a blank page |
mermaid | string | None | Mermaid source to open instead. The editor converts it to draw.io shapes, and a subgraph to a swimlane |
title | string | None | Shown in the editor's title bar |
onSave(source, { exit }) | (source, { exit }) => void | Required | Called with the XML on Save, and with exit: true on Save and Exit |
onExit() | () => void | Required | Called when the editor closes, also after Save and Exit |
onAutosave(source) | (source) => void | None | Turns on autosave, and is called with the XML after every change |
onError(message) | (message) => void | None | Called 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/drawioframe.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.