Embed mode

Embed mode allows you to integrate the draw.io editor into your own application using an iframe. When the embed=1 URL parameter is set, the editor communicates with the parent page or opener window via postMessage. This mode is only supported on https://embed.diagrams.net.

Once the page has loaded, it sends a ready message to the opener or parent window. After receiving this message, the host application can send diagram data as XML or compressed XML. The editor returns XML when the user clicks Apply, or an empty string when the user clicks Cancel.

URL parameters

The following URL parameters are available in embed mode:

• spin=1: Shows a Loading… spinner while waiting for diagram data. You can also pass a custom message, for example spin=Loading+diagram....
• modified=0: Disables the modified-state update after Save is selected and enables a status message after changes are made. If set to 0, the status bar is cleared after changes. Otherwise, the value is used as a resource key. You can also specify this setting in the load message.
• keepmodified=1: If modified specifies a resource key, this parameter maintains the modified state after Save is selected.
• libraries=1: Enables the shape libraries in the left panel. The default is 0 (disabled).
• noSaveBtn=1: Replaces the Save button with a Save and Exit button. You can also specify this setting in the load message. When this parameter is set, the saveAndExit parameter is ignored.
• saveAndExit=1: Displays an additional Save and Exit button alongside the Save button. You can also specify this setting in the load message. If noSaveBtn=1 is set, use saveAndExit=0 to hide the Save and Exit button.

• noExitBtn=1: Hides the Exit button. You can also specify this setting in the load message.

  Note: To hide all buttons in embed mode, use saveAndExit=0&noSaveBtn=1&noExitBtn=1.

• ready=message: Specifies the message to send when the editor is ready. The default is ready. This parameter is ignored when the JSON protocol is used.
• returnbounds=1: Returns a JSON structure with the diagram bounds immediately after receiving the diagram XML.
• proto=json: Enables the JSON protocol for message passing.
• configure=1: Sends a configure event and waits for a configure action before initialising the editor. See Configuration.

Configuration

When the configure=1 URL parameter is set, the editor sends {event: 'configure'} to the parent window and waits for {action: 'configure', config: obj} before creating the main application and sending the init event. The obj value follows the format described in Configure the draw.io editor, for example:

{"action": "configure", "config": {"defaultFonts": ["Humor Sans"]}}

JSON protocol

When proto=json is set, the editor and host application exchange JSON-encoded messages via postMessage. This section describes the available events and actions.

Initialisation

When the editor is ready, it sends {event: 'init'} and expects a load action in response.

Load action

The load action provides the diagram data to the editor:

{"action": "load", "xml": "<mxGraphModel>...</mxGraphModel>"}

The xml value can be any supported diagram format, including:

• Standard draw.io XML
• SVG or PNG files with embedded XML
• PNG data URIs with base64 encoding
• SVG data URIs with UTF-8 or base64 encoding
• Visio files as data URIs with a data:application/vnd.visio;base64 prefix
• Lucidchart and Gliffy files as JSON strings

The legacy parameter name xmlpng can still be used for PNG+XML data.

You can also import specific data formats using a descriptor object:

{"action": "load", "descriptor": {"format": "csv", "data": "..."}}
{"action": "load", "descriptor": {"format": "mermaid", "data": "..."}}

The load action supports the following optional parameters:

After the diagram loads, the editor returns a load event message containing diagram size information.

Autosave

When autosave is enabled in the load message, the editor sends {event: 'autosave', xml: '...'} whenever the diagram changes. Changes that trigger autosave include modifications to the model, grid size, shadow visibility, page format, page scale, background, folding, math rendering, grid, guides, and page view settings.

Save and exit events

• Save: When the user clicks Save, the editor sends a message with event: 'save' and xml: '...' containing the current diagram XML.
• Save and Exit: When the user clicks Save and Exit, the save message includes an additional exit: true property.
• Exit: When the user clicks Exit, the editor sends {event: 'exit', modified: boolean}.
• Open Link: When the user clicks a link in the editor, the editor sends {event: 'openLink', href: String, target: String} and attempts to open the link in the specified target (default: _blank).

Actions

The host application can send the following actions to the editor at any time:

merge

Merges the given XML into the current diagram. The xml parameter can be XML or a PNG or SVG data URI.

{"action": "merge", "xml": "..."}

Returns {event: 'merge', error: '...', message: ...} with the incoming message and an optional error. If the merge succeeds, error is null.

dialog

Displays a dialog in the editor window. Use titleKey, messageKey, and buttonKey instead of title, message, and button for translatable strings.

{"action": "dialog", "title": "...", "message": "...", "button": "...", "modified": true}

prompt

Displays a prompt dialog in the editor window. Use titleKey and okKey for translatable strings.

{"action": "prompt", "title": "...", "ok": "...", "defaultValue": "..."}

Returns {event: 'prompt', value: '...', message: ...} when the user clicks OK.

template

Shows the template dialog. This is typically sent instead of a load action to let the user create a diagram from a template. When the user clicks Cancel, an exit event is sent.

{"action": "template"}

Set callback: true to receive the selected template data for validation. The callback message is {event: 'template', xml: '...', blank: boolean, name: '...', message: ...} where blank is true if the user selected a blank diagram.

layout

Runs an array of layouts using the same format as Arrange > Layout > Apply.

{"action": "layout", "layouts": [...]}

draft

Shows a draft recovery dialog. Returns {event: 'draft', result: '...', message: ...} with result set to 'Edit', 'Discard', or 'ignore'. If an error occurs, the response contains error instead of result.

{"action": "draft", "xml": "...", "name": "...", "editKey": "...", "discardKey": "...", "ignore": true}

Set ignore to true to include an Ignore option.

status

Displays a message in the status bar. Use messageKey instead of message for translatable strings.

{"action": "status", "message": "...", "modified": true}

The optional modified flag updates the modified state of the editor.

spinner

Shows or hides a loading spinner. Use messageKey instead of message for translatable strings.

{"action": "spinner", "message": "...", "show": true, "enabled": true}

Set show to false to hide the spinner.

export

Requests an export of the current diagram. Returns {event: 'export', format: '...', data: '...', xml: '...', message: ...} where data is a valid data URI for the requested format.

{"action": "export", "format": "svg"}

Supported formats:

Additional parameters for png and xmlpng:

Additional parameters for svg and xmlsvg:

Use the optional xml parameter in any export action to specify custom diagram XML to export.

textContent

Requests the text content of the current diagram.

{"action": "textContent"}

Returns {event: 'textContent', data: '...'}.

viewport

Sets the viewport position and scale.

{"action": "viewport", "viewport": {...}}

Error handling

If the editor receives an unrecognised message, it responds with {error: 'unknownMessage', data: '...'} where data is the string representation of the incoming message.

Examples

• Introduction and example
• GitHub example
• Simple embedding walkthrough