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.

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


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\" 

By default, when exporting a custom shape library from the 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 configuration.

Compress an mxGraphModel XML property

To compress the XML property, use the conversion tool.

The example above when compressed looks like:

  "xml": "jVBLDoMgED3N7BE2XVdbV131BKROhASE4LTq7TsVWuPCpAuS