Skip to main content

File format for custom shape libraries

Custom shape libraries are used to store custom shapes, favourite shapes, freehand shapes, icons, images and even custom templates (entire diagrams).

A custom library file is an XML file, which must have an enclosing <mxlibrary> node containing a JSON array and follow a specific format. The node has an optional tags attribute for searching library entries in the sidebar.

Required properties​

  • h: the height of the shape, group or image in pixels
  • w: the width of the shape, group or image in pixels
  • <xml> or a <data> property

Required attributes for data properties

  • "data": must specify the format of the data in this property, e.g. "data:image/png,[...]"
  • "aspect": to sepcify a "fixed" ratio (used when resizing the image)
  • "style": to specify additional style attributes that will be added to the default style of this image cell, e.g. "resizable=0;rotatable=0;" to prevent resizing and rotating the image.

Optional properties​

  • title: displayed when hovering over the shape in the custom library
  • tags: space-separated list of tags for searching in the sidebar (all tags from the library are added to each entry)

Examples:​

Uncompressed XML properties must be escaped​

<xml> properties contain a <mxGraphModel> description of a shape or diagram, which may or may not be compressed in the library file. If they are left uncompressed, you must escape much of the XML code.

For example, < must be written as &lt; and > as &gt;. All " characters must be preceded by a backslash like \".

The resulting XML will look as follows when uncompressed:

  "xml": "&lt;mxGraphModel&gt;&lt;root&gt;&lt;mxCell 
  id=\"0\"/&gt;&lt;mxCell id=\"1\" parent=\"0\"/&gt;&lt;
  mxCell id=\"2\" value=\"Test3\" style=\"whiteSpace=wrap;
  html=1;fillColor=#ffffff;strokeColor=#000000;\" vertex=\"1\" 
  parent=\"1\"&gt;&lt;mxGeometry width=\"120\" height=\"60\" 
  as=\"geometry\"/&gt;&lt;/mxCell&gt;&lt;/root&gt;&lt;/mxGraphModel&gt;"

By default, when exporting a custom shape library from the draw.io editor, the entries in the JSON array will be uncompressed (and properly escaped).

If you want to store these compressed by default, set compressXml=true in the draw.io configuration.

Compress an mxGraphModel XML property

To compress the XML property, use the draw.io conversion tool.

The example above when compressed looks like:

  "xml": "jVBLDoMgED3N7BE2XVdbV131BKROhASE4LTq7TsVWuPCpAuS
  95lH3gyo2s9t0tHcQocO1AVUnUKgjPxco3Mghe1ANSCl4AfyeuBWqyui
  TjjQPwGZAy/tnpiVLIy0uCJwwMaRyXkylvAe9ePjTNyZNUOeSzcVw5D0
  0GP5EBPhfFhqlUqjFoNHSguPTLYjkydOubcwaHtDe02Pmfe/5LYhg7Lk
  l27HXL3drd8="