Configure the draw.io editor

The draw.io editor can be configured in draw.io for Confluence Server/Data Center/Cloud, Jira Server, embed mode, the online editor, and the desktop app. You can customise the following aspects:

Fonts and web fonts
Colour palettes and themes
Shape and connector styling
Built-in and custom libraries in the left panel
CSS for the editor appearance
Entry dimensions in the left panel
XML for blank diagrams and libraries
Global variables
XML compression
Default connector length
Default autosave delay
AI diagram generation

The following video shows what can be customised in draw.io.

Accessing the configuration

Confluence Data Center or Server: Go to your instance’s settings as an administrator, scroll down to the draw.io add-on section in the left navigation, and click on the Configuration tab.

draw.io Configuration in Confluence Server

Confluence Cloud: As an administrator, go to the draw.io Configuration section in your instance’s Settings.

draw.io Configuration in Confluence Cloud

Jira Server: Click on the Settings icon as an administrator. Select Manage apps (or Manage add-ons in older Jira versions). Open the draw.io add-on configuration in the left navigation, and click on the Configuration tab.

draw.io Configuration in Jira Server

Embedded: Add the configure=1 URL parameter and send the JSON configuration via postMessage.

Online and Desktop: Select Extras > Configuration to customise the draw.io editor.

Format

The configuration is represented as a JSON (JavaScript Object Notation) string with the options described below. You can also use the graphical configuration editor to build and edit the JSON configuration.

Fonts

defaultFonts: An array of font family names (strings) or custom font objects {"fontFamily": name, "fontUrl": url} for the format panel font drop-down list. See the example below.
customFonts: An array of font family names or custom font objects {"fontFamily": name, "fontUrl": url} to be added before defaultFonts (9.2.4 and later). For example: ["Helvetica", {"fontFamily": "Rock Salt", "fontUrl": "https://fonts.googleapis.com/css?family=Rock+Salt"}].
Note: Fonts without a fontUrl must be installed on the server and all client devices, or be added using the fontCss option (6.5.4 and later).
fontCss: A string containing CSS @font-face rules for web fonts used in diagrams. For example, to use a font file attached to a Confluence page: {"fontCss": "@font-face { font-family: 'Marvel'; src: url(/confluence/download/attachments/720900/Marvel-Regular.ttf?api=v2) format('truetype')}"}.
These fonts are used for displaying diagrams in the editor and creating images in Google Chrome, Firefox, and Microsoft Edge. All other browsers require the font to be installed on the server side.
Confluence Server and Data Center: To create images in the browser, the font must be on the same domain and include a CORS header, or it will be proxied via the Confluence server.
Confluence Cloud: The font URL must be publicly accessible and allow access to the draw.io origin via a CORS header:
"fontCss": "@font-face { font-family: 'Waltograph'; src: url(https://fontlibrary.org/assets/fonts/waltograph/23a40698cd1bb84f930b7a0884c134a6/ab260a56f2b852b78f81eac337e0a2fc/WaltographRegular.otf) format('opentype')}" and "customFonts": ["Waltograph"]
Note: All fonts are downloaded to the client when an image is created and the diagram is saved, so keep the number of custom fonts to a minimum. The external image service does not currently support custom fonts.

Colours

presetColors: Colour codes for the upper palette in the colour dialog. Use codes without a leading #, null for a blank entry, or a light-dark colour function with a leading #.
customPresetColors: Colour codes to be added before presetColors (9.2.5 and later). Uses the same format as presetColors.
defaultColors: Colour codes for the lower palette in the colour dialog. Uses the same format as presetColors.
colorNames: A map of colour codes to display names, used as tooltips. Use uppercase codes without a leading #, or light-dark colour functions with a leading #. For example: {"FFFFFF": "White", "000000": "Black"}.
defaultColorSchemes: Available colour schemes in the style section at the top of the format panel. Use a leading # for colour codes, or light-dark colour functions with a leading #. Supported keys are fill, stroke, gradient, and font (font is ignored for connectors). An optional title can be added for a tooltip. An optional border can define the CSS border width and type, for example "2px solid" or "3px dashed" (you must include the border type).
customColorSchemes: Colour schemes to be added before defaultColorSchemes (9.2.4 and later).

Default styles

defaultTextStyle: Default style for text elements in the sidebar, toolbar, menus, and shape picker. The default value is text;html=1;whiteSpace=wrap;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;rounded=0;.
defaultVertexStyle: Defines the initial default style for vertices (shapes). These values are copied to every new vertex, overriding all inherited styles. Use a minimal set of key/value pairs to avoid unintended overrides. To find the correct keys and values, apply a style in the editor and inspect it via Edit Style (Ctrl+E) (6.5.2 and later).
defaultEdgeStyle: Defines the initial default style for edges (connectors). Uses the same format and behaviour as defaultVertexStyle.
For example, to set a default fontFamily of Courier New on all vertices and edges: {"defaultVertexStyle": {"fontFamily": "Courier New"}, "defaultEdgeStyle": {"fontFamily": "Courier New"}}.

styles: An array of objects defining the colours for the Style tab of the format panel when the selection is empty. Each object can contain:

commonStyle: Applied to both vertices and edges (fontColor, fillColor, strokeColor, gradientColor).
vertexStyle: Applied to vertices only.
edgeStyle: Applied to edges only.
graph: Contains background and gridColor.

An empty object applies the default colours. For example:

[ {},
{
  "commonStyle": {
    "fontColor": "#5C5C5C",
    "strokeColor": "#006658",
    "fillColor": "#21C0A5"
  }
},
{
  "commonStyle": {
    "fontColor": "#095C86",
    "strokeColor": "#AF45ED",
    "fillColor": "#F694C1"
  },
  "edgeStyle": {
    "strokeColor": "#60E696"
  }
},
{
  "commonStyle": {
    "fontColor": "#E4FDE1",
    "strokeColor": "#028090",
    "fillColor": "#F45B69"
  },
  "graph": {
    "background": "#114B5F",
    "gridColor": "#0B3240"
  }
}
]

Libraries

defaultLibraries: A semicolon-separated string of library keys (unique names) to display initially in the left panel, for example "general;uml;company-graphics". Possible keys include custom entry IDs from the libraries option, or keys for the libs URL parameter (6.5.2 and later). The default value is "general;uml;er;bpmn;flowchart;basic;arrows2".
enabledLibraries: An array of library key strings that will be available in the More Shapes dialog. Set to null to show all libraries, or use an empty array to hide all libraries. For example: ["general", "uml"] (9.2.5 and later).
libraries: An array of objects defining additional libraries and sections for the left panel and the More Shapes dialog, in the format [section1, ..., sectionN] where:
- Each section has the form {title: resource, entries: [entry1, ..., entryN]}.
- Each entry has the form {id: string, preview: string, title: resource, desc: resource, libs: [lib1, ..., libN]}.
- Each lib has the form {title: resource, url: string OR data: string, tags: string}.
- sections are used for the groups in the More Shapes dialog.
- entries are the items within each section. Each entry may have one or more libraries associated with it. The id must be unique, preview is the URL of a preview image, and desc is used before or instead of the preview as a description (pre-formatted text supporting linefeeds).
- In libs, resource is a language resource defined as {main: string, xy: string} where xy is a country code (e.g. es, fr, de) and main is the fallback when no string is defined for the current country code.
- In libs, tags is an optional string with a space-separated list of searchable tags.
- libs may reference an external resource via url or define entries directly via data, which contains the array from <mxlibrary>...</mxlibrary> in library files. By default, all entries with data and the first 20 entries with url are prefetched and added to the search index. To prefetch additional entries with url, add "prefetch": true to the respective lib (9.2.5 and later).
  For example:
```
[ {
 "title": {
 "main": "Company"
 },
 "entries": [ {
"id": "company-graphics",
"title": {
  "main": "Graphics",
  "de": "Grafiken"
},
"desc": {
  "main": "Collection of Graphics for Company",
  "de": "Sammlung von Grafiken für Firma"
},
"libs": [ {
    "title": {
      "main": "Graphics for Company",
      "de": "Grafiken für Firma"
    },
    "data": [ {
        "xml": "jZLBbsMgDIafhmuUgKr1mqZbL5u0VyCJF5BMHIHbpG9fEti6Tqq0A5L5/NuYH4Rq3HLyejIf1AMK9SpU44k4RW5pAFHI0vZCHYWUZVxCvj3JVlu2nLSHkf9TIFPBReMZEkkg8BUz6HUwsMpLoQ50ZrQjNDSO0HGGhl0c/FjFUKMdxhh38XzwEaBuAT8pWLb0kLiAZ9tpfP8jaImZ3C9BnVsyTZEGo6d1MLcMq2nFDC3SQKHovZ4tySj5sogNIfltflXVu0Ot8j1jT1ieerWhbNQJyAH7a5TMtmeTFDtZZIcM2MHkupey2CeqQyLDT/Xd/Bhk/7+393fecg/f4AY=",
        "w": 52.2,
        "h": 70.8,
        "aspect": "fixed"
      } ]
  } ]
 } ]
} ]
```
  This configuration produces the following More Shapes dialog when combined with enabledLibraries: []:
defaultCustomLibraries: An array of IDs to load custom libraries.
- In Atlassian Confluence, define the IDs as A1...An, for example {"defaultCustomLibraries": ["A1"]}. To find the ID for a custom library, hover over the entry in the Select Library dialog or the library title in the left panel and wait for the tooltip, e.g. my library (A1), where A1 is the ID. If no tooltip appears, open the library in a diagram, save the diagram, then check the <mxAtlasLibraries> section in the diagram file attached to the page (6.5.2 and later).
- Alternatively, use a URL-encoded URI as the ID to load a library from a URL, for example {"defaultCustomLibraries": ["U%2Fconfluence%2Fdownload%2Fattachments%2F720900%2FScratchpad.xml%3Fapi%3Dv2"]}.
  Note: To encode a URL, enter the URL into the URL encode tool and select URL Encode.
- To load libraries from the libraries section above, use the defaultLibraries setting instead.
enableCustomLibraries: Specifies whether the open and new library functions are enabled (true or false, the default is true).
appendCustomLibraries: Specifies whether custom libraries should appear after built-in libraries (true or false, the default is false) (22.1.7 and later).
expandLibraries: Specifies whether libraries are expanded by default (true or false, the default is true) (22.1.6 and later).
templateFile: The URL of the source file for the Templates dialog. Multiple <template> and <clibs> tags are allowed. Example

CSS and appearance

css: A string containing CSS rules to customise the draw.io user interface. For example, to change the menu bar background colour: {"css": ".geMenubarContainer { background-color: #c0c0c0 !important; } .geMenubar { background-color: #c0c0c0 !important; }"} (6.5.2 and later).
darkColor: The background colour for dark mode. The default is #2A2A2A.
darkColorVar: The name of the CSS variable used for the dark colour. The default is --ge-dark-color.
defaultAdaptiveColors: The default mode for adaptive colours. Accepts auto, simple, or none. The default is simple in the desktop app and auto in all other editions (26.0.0 and later).
enableCssDarkMode: Specifies whether CSS should be used for dark mode. The default is true. Deprecated in 26.0.0. Use defaultAdaptiveColors instead. If set to true and defaultAdaptiveColors is not specified, defaultAdaptiveColors is set to simple.
enableLightDarkColors: Specifies whether the light-dark CSS colour function should be used. The default is true if the browser supports it.

thumbWidth / thumbHeight: The width and height (in pixels) for entries in the left panel (6.5.4 and later).
sidebarWidth: The initial width of the sidebar in pixels.
sidebarTitles: Specifies whether titles in the sidebar are visible. The default is false.
sidebarTitleSize: The font size (in points) for titles in the sidebar. The default is 8.

Grid, page, and zoom

defaultGridSize: The default grid size for new diagrams. The default is 10 (22.1.5 and later).
gridSteps: The number of minor grid steps (14.3.2 and later).
defaultGridEnabled: Whether the grid is initially enabled (true or false).
defaultPageVisible: Whether the page is initially visible (true or false).
pageFormat: The default page format, for example {"width": 1169, "height": 1654} for DIN A3, using inches multiplied by 10 for width and height (15.0.0 and later).
zoomFactor: The zoom factor for mouse wheel and trackpad zoom. The value must be greater than 1. The default is 1.2 (14.7.0 and later).
zoomWheel: Specifies whether the mouse wheel is used for zoom without any modifiers (true or false). The default is false (15.0.6 and later).

Editor behaviour

simpleLabels: Set to true to disable word wrap and complex formatting for labels by default, avoiding foreignObject elements in SVG output (14.5.9 and later).
pasteAtMousePointer: Set to true to paste content at the mouse pointer location instead of the centre of the viewport (28.2.6 and later).
fitDiagramOnLoad: Set to true to fit the diagram to the window on load when it is only partially visible (29.3.9 and later).
selectParentLayer: Set to true to select the parent layer of the current selection (22.1.4 and later). The default is false.
updateDefaultStyle: Whether the default styles should be updated when styles are changed. The default is false.
enableInlineToolbar: Specifies whether the inline toolbar is enabled. The default is true.
enableWindowDocking: Specifies whether window docking is enabled. The default is true.
showLinkIcons: Specifies whether link icons are shown. The default is false.
showTooltipIcons: Specifies whether tooltip icons are shown. The default is false.
enableNativeClipboard: Specifies whether the native clipboard should be used. The default is true if the editor is not inside an iframe.

Diagram content and XML

emptyDiagramXml: The XML for blank diagrams (6.5.4 and later).
emptyLibraryXml: The XML for blank libraries (6.5.4 and later).
defaultEdgeLength: The default length for new connectors (7.2.4 and later).
compressXml: Specifies whether the XML output should be compressed. The default is false.
globalVars: A JSON object of key/value pairs defining global variables for system-wide placeholders. Keep the number of global variables small.

Images and SVG

maxImageBytes: The maximum size for images in bytes. The default is 1000000.
maxImageSize: The maximum width or height of an image (the lower value is used). The default is 520.
replaceSvgDataUris: Specifies whether data URIs should be replaced with SVG sub-trees in SVG export. The default is true.
foreignObjectImages: Specifies whether foreignObject alternate content should be replaced with an image of the HTML text. The default is true.
removeImageMetadata: Specifies whether metadata should be removed from images. The default is true.
includeDiagram: The default for including diagram data in export dialogs (15.0.4 and later).

enableExportUrl: Specifies whether the export URL should be enabled. The default is true.
restrictExport: Disables exporting diagrams to other formats. This does not prevent users from obtaining text or image formats of the diagram, but makes it more difficult. The default is false.

Autosave and storage

autosaveDelay: The delay (in milliseconds) between the last change and the autosave of the file (10.4.7 and later).
settingsName: A custom name for storing user settings (typically used in embed mode). Settings are stored in local storage as .{name}-config.

Real-time collaboration

shareCursorPosition: The default value for sharing cursor positions in real-time collaboration. The default is true.
showRemoteCursors: The default value for showing remote cursors in real-time collaboration. The default is true.

Miscellaneous

oneDriveInlinePicker: Specifies whether the inline picker for OneDrive should be used. The default is true if the inlinePicker URL parameter is not set.
lockdown: Disables data transmission apart from directly between your browser and your selected data storage location. The default is false.
version: The current version of the configuration (any string, e.g. "1.0"). If this value differs from the last used version, the current client-side settings (.drawio-config) are reset. The default is null. Change this to force the stored settings to be reset and apply the current configuration (7.2.8 and later).
override: Ignores the current client-side settings if set to true (9.2.5 and later).

AI diagram generation support and customisation

You can configure custom LLM backends, generation actions, and other options for AI-powered diagram generation through various configuration parameters.
The diagram Generate options can be customised in draw.io to include specific actions or allow you to choose specific AI models

See all custom LLM and AI diagram generation options

Diagram generation is enabled by default only in the online draw.io editor at app.diagrams.net.

Atlassian administrators can enable it in the draw.io app configuration in Confluence with "enableAi": true.

Additional options for the desktop app

desktopAutoSync: Automatically synchronise diagrams when the local file is changed externally and autosave is enabled. The default is true.

Additional options for Confluence Server and Data Center

inplaceEdits: Disables the ability to launch the diagram editor from the viewer if set to false. The default is true (8.3.13 and later).
forceSimpleViewer: Forces the simple diagram viewer for every diagram if set to true. The default is false (8.4.0 and later).
debug: Set to true to enable debug output.
defaultMacroParameters: A JSON object defining overrides for default macro parameters (9.2.5 and later):
- border (boolean): Shows a border around the viewer. The default is true.
- width (integer): The default width of the viewer. The default is blank.
- lightbox (boolean): Enables the lightbox (large viewer). The default is true.
- simpleViewer (boolean): Shows the simple viewer. The default is false.
- toolbarStyle (string): Controls toolbar display. The default is "top". Accepted values:
  - "top": Shows the toolbar above the viewer on mouse hover.
  - "inline": Shows the toolbar inside the viewer on mouse hover.
  - "hidden": Hides the toolbar.
- links (string): Controls link behaviour. The default is "auto". Accepted values:
  - "auto": Opens local links in the current window and external links in a new window.
  - "blank": Opens all links in a new window.
  - "self": Opens all links in the current window.

Note: Diagram editor plugins are not available on Confluence Server or Data Center.

Additional options for Confluence Cloud

ui: A string specifying the theme for the user interface. Choose one of the following: kennedy, atlas (default), dark, or min.

More configuration options for draw.io in Confluence Cloud

Example

The following is an example JSON configuration with default values (variables that are omitted use these defaults):

{ "defaultFonts": ["Helvetica", "Verdana", "Times New Roman", "Garamond", "Comic Sans MS", "Courier New", "Georgia", "Lucida Console", "Tahoma"],
  "presetColors": ["E6D0DE", "CDA2BE", "B5739D", "E1D5E7", "C3ABD0", "A680B8", "D4E1F5", "A9C4EB", "7EA6E0", "D5E8D4", "9AC7BF", "67AB9F", "D5E8D4", "B9E0A5", "97D077", "FFF2CC", "FFE599", "FFD966", "FFF4C3", "FFCE9F", "FFB570", "F8CECC", "F19C99", "EA6B66"],
  "defaultColorSchemes": [
  [ null, { "fill": "#f5f5f5", "stroke": "#666666" },
     {	"fill": "#dae8fc", "stroke": "#6c8ebf" },
     {	"fill": "#d5e8d4", "stroke": "#82b366" },
     {	"fill": "#ffe6cc", "stroke": "#d79b00" },
     {	"fill": "#fff2cc", "stroke": "#d6b656" },
     { "fill": "#f8cecc", "stroke": "#b85450" },
     {	"fill": "#e1d5e7", "stroke": "#9673a6" }],
	[ null, { "fill": "#f5f5f5", "stroke": "#666666", "gradient": "#b3b3b3" },
     {	"fill": "#dae8fc", "stroke": "#6c8ebf",	"gradient": "#7ea6e0" },
     {	"fill": "#d5e8d4", "stroke": "#82b366",	"gradient": "#97d077" },
     {	"fill": "#ffcd28", "stroke": "#d79b00",	"gradient": "#ffa500" },
     {	"fill": "#fff2cc", "stroke": "#d6b656",	"gradient": "#ffd966" },
     {	"fill": "#f8cecc", "stroke": "#b85450",	"gradient": "#ea6b66" },
     {	"fill": "#e6d0de", "stroke": "#996185",	"gradient": "#d5739d" }],
	[ null, { "fill": "#eeeeee", "stroke": "#36393d" },
     {	"fill": "#f9f7ed", "stroke": "#36393d" },
     {	"fill": "#ffcc99", "stroke": "#36393d" },
     {	"fill": "#cce5ff", "stroke": "#36393d" },
     {	"fill": "#ffff88", "stroke": "#36393d" },
     {	"fill": "#cdeb8b", "stroke": "#36393d" },
     {	"fill": "#ffcccc", "stroke": "#36393d" }]
	],
  "defaultColors": ["none", "FFFFFF", "E6E6E6", "CCCCCC", "B3B3B3", "999999", "808080", "666666", "4D4D4D", "333333", "1A1A1A", "000000", "FFCCCC", "FFE6CC", "FFFFCC", "E6FFCC", "CCFFCC", "CCFFE6", "CCFFFF", "CCE5FF", "CCCCFF", "E5CCFF", "FFCCFF", "FFCCE6", "FF9999", "FFCC99", "FFFF99", "CCFF99", "99FF99", "99FFCC", "99FFFF", "99CCFF", "9999FF", "CC99FF", "FF99FF", "FF99CC", "FF6666", "FFB366", "FFFF66", "B3FF66", "66FF66", "66FFB3", "66FFFF", "66B2FF", "6666FF", "B266FF", "FF66FF", "FF66B3", "FF3333", "FF9933", "FFFF33", "99FF33", "33FF33", "33FF99", "33FFFF", "3399FF", "3333FF", "9933FF", "FF33FF", "FF3399", "FF0000", "FF8000", "FFFF00", "80FF00", "00FF00", "00FF80", "00FFFF", "007FFF", "0000FF", "7F00FF", "FF00FF", "FF0080", "CC0000", "CC6600", "CCCC00", "66CC00", "00CC00", "00CC66", "00CCCC", "0066CC", "0000CC", "6600CC", "CC00CC", "CC0066", "990000", "994C00", "999900", "4D9900", "009900", "00994D", "009999", "004C99", "000099", "4C0099", "990099", "99004D", "660000", "663300", "666600", "336600", "006600", "006633", "006666", "003366", "000066", "330066", "660066", "660033", "330000", "331A00", "333300", "1A3300", "003300", "00331A", "003333", "001933", "000033", "190033", "330033", "33001A"],
	"defaultVertexStyle": {},
	"defaultEdgeStyle": {
		"edgeStyle": "orthogonalEdgeStyle",
		"rounded": "0",
		"jettySize": "auto",
		"orthogonalLoop": "1" },
	"defaultLibraries": "general;images;uml;er;bpmn;flowchart;basic;arrows2",
	"defaultCustomLibraries": [],
	"defaultMacroParameters": {
		"border": false,
		"toolbarStyle": "inline" },
	"css": "",
	"fontCss": "",
	"thumbWidth": 46,
	"thumbHeight": 46,
	"emptyDiagramXml": "<mxGraphModel><root><mxCell id='0'/><mxCell id='1' parent='0'/></root></mxGraphModel>",
	"emptyLibraryXml": "<mxlibrary>[]</mxlibrary>",
	"defaultEdgeLength": 80 }

The configuration of the online version is stored in your browser in local storage under the key .configuration.
The draw.io configuration is stored in your browser's local storage

The current settings of the editor (such as recent colours, currently open libraries, etc.) persist in your browser in local storage under the key .drawio-config:
Current settings for draw.io are saved in local storage in your browser

You can add defaultEdgeLength and autosaveDelay directly to .drawio-config to override the default values for the web app in your browser.

Deleting the current settings or configuration

Open the browser developer tools (e.g. More Tools > Developer Tools in Google Chrome).
Go to the Application tab and select Storage > Local Storage > your_domain_name.
Right-click .drawio-config in the key-value table and delete it.

Fixing errors in your configuration

If the configuration has an invalid format, a configuration error is shown in the browser console when the diagram editor opens. Replace double-escaped quotes (\") with single-escaped quotes ("), to ensure the configuration is valid JSON. You can verify it with a JSON validator such as JSONLint.

Configuring the online app

You can create a link to configure the online version of draw.io by clicking Link in the Configuration dialog: click on Help > Configuration.