Home

Viz.js

API

Viz(src, options={ format="svg", engine="dot", scale, images=[{ path, width, height }], totalMemory=16777216 })

• src is a string representing the graph to render in the DOT language.
• options
  • format sets the output format, and may be one of "svg", "xdot", "plain", "ps", "json", or "png-image-element".
  • engine sets the Graphviz engine to use, and may be one of "circo", "dot", "fdp", "neato", "osage", or "twopi".
  • scale sets the scale factor for the "png-image-element" format. If this is not specified, window.devicePixelRatio will be used if available, and 1 if not.
  • images specifies image dimensions to use when rendering nodes with image attributes. This is an array of objects, { href, width, height }. href may be a filename ("example.png"), a relative or absolute path ("/images/example.png"), or a URL ("http://example.com/image.png"). Dimensions may be specified with units: in, px, pc, pt, cm, or mm. If no units are given or dimensions are given as numbers, points (pt) are used. Graphviz does not actually load image data when this option is used — images are referenced with the dimensions given, eg, in SVG by an <image> element with width and height attributes.
  • files specifies files to make available to Graphviz using Emscripten's in-memory filesystem. This is an array of objects, { path, data }. path is a string and may be given as an absolute or relative path, and data is a string. Files are created relative to the root, which is the working directory.
  • totalMemory sets the total memory available for the Emscripten module instance. This should be a power of 2. The default of 16MB should be sufficient for most cases — only consider using a larger number if you run into the error "Cannot enlarge memory arrays".

Parses src and renders a graph according to the options given. Output is a string, except when using the "png-image-element" format, when it is an instance of HTMLImageElement.

For example:

result = Viz("digraph { a -> b; }");
result = Viz("digraph { a -> b; }", { format: "png-image-element", scale: 2 });
result = Viz("graph { n0 -- n1 -- n2 -- n3 -- n0; }", { engine: "neato" });
result = Viz("digraph { x -> y -> z; }", { format: "plain" });
result = Viz("digraph { a[image=\"test.png\"]; }", { images: [ { path: "test.png", width: "400px", height: "300px" } ] });

If Graphviz encounters an error, Viz will throw an Error object with the error message.

Viz.svgXmlToPngImageElement(svgXml[, scale[, callback]])

• svgXml is an SVG XML string, as may be obtained from the Viz function using the "svg" format option.
• scale sets the scale factor for the output. If this is not specified, window.devicePixelRatio will be used if available, and 1 if not.
• callback is an optional Node-style callback. If specified, it is given two arguments, (err, image). If not specified, Viz.svgXmlToPngImageElement returns an instance of HTMLImageElement.

Converts svgXml to a PNG HTMLImageElement. If callback is specfied, image is loaded by the time the callback is invoked.

Viz.svgXmlToPngBase64(svgXml, scale, callback)

• svgXml is an SVG XML string, as may be obtained from the Viz function using the "svg" format option.
• scale sets the scale factor for the output. If this is given as undefined, window.devicePixelRatio will be used if available, and 1 if not.
• callback is a Node-style callback. It is given two arguments, (err, data).

Converts svgXml to a PNG represented as a Base64 string. This function requires a callback, unlike svgXmlToPngImageElement.

Supported Graphviz features

These engines are supported:

• circo
• dot
• fdp
• neato
• osage
• twopi

These formats are supported:

• svg
• xdot
• plain
• ps
• json

PNG output

Viz.js provides the "png-image-element" format in addition to the regular Graphviz formats. This returns an HTMLImageElement which can be inserted into the document.

image = Viz("digraph g { a -> b; }", { format: "png-image-element" });
document.body.appendChild(image);

However, this won't work in a Web Worker context. In that case, ask for the "svg" format in the worker and convert using the accessory function Viz.svgXmlToPngImageElement in the window context. See tests/png.js for an example.

Internet Explorer support

Internet Explorer 10 and 11 require Fabric.js as an optional dependency for PNG output. Viz.js will look for a fabric object as a member of the global object with a loadSVGFromString() function and use that if present.

Caveats

Fonts

When used in Viz.js, Graphviz only knows about font metrics for Courier, Times, Helvetica, and Arial, even though it will include other font names in its output if they are specified. When another font name is specified, Graphviz will fall back to using the metrics for Times. This can result in a label being drawn outside of its node.

If you would like to use other fonts, one workaround is to choose a font with similar metrics to Times and to add extra space around labels using the margin attribute.