Viz.js - API

Viz.js is a collection of packages for working with Graphviz in JavaScript.

@viz-js/lang-dot — CodeMirror language support for the Graphviz DOT language.
@viz-js/viz — WebAssembly build of Graphviz with a simple JavaScript wrapper.

@viz-js/lang-dot

CodeMirror language support for the Graphviz DOT language.

dot() → LanguageSupport: Returns a LanguageSupport instance for DOT.

@viz-js/viz

WebAssembly build of Graphviz with a simple JavaScript wrapper.

Usage

ES module

The Viz.js ES module is published as a single file, including its WebAssembly code. It exports a function, instance, which encapsulates decoding the WebAssembly code and instantiating the WebAssembly and Emscripten modules. This returns a promise that resolves to an instance of the Viz class, which provides methods for rendering graphs.

import { instance } from "@viz-js/viz";

instance().then(viz => {
  const svg = viz.renderSVGElement("digraph { a -> b }");

  document.getElementById("graph").appendChild(svg);
});

The instance can be used to render multiple graphs.

UMD Bundle

The package also includes a UMD bundle, lib/viz-standalone.js. This assigns the instance function to a global Viz object.

<div id="graph"></div>

<script src="viz-standalone.js"></script>
<script>
  Viz.instance().then(function(viz) {
    var svg = viz.renderSVGElement("digraph { a -> b }");

    document.getElementById("graph").appendChild(svg);
  });
</script>

graphvizVersion: string

The version of Graphviz used for this build.

formats: string[]

The names of the Graphviz output formats supported in this build.

engines: string[]

The names of the Graphviz layout engines supported in this build.

instance() → Promise<Viz>

Returns a promise that resolves to an instance of the Viz class.

class Viz

The Viz class isn't exported, but it can be instantiated using the instance function.

The graphvizVersion, formats, and engines getters return the results of querying the Graphviz context at runtime, but since there currently isn't any way to modify which output formats or layout engines are available, they return the same values as the constants graphvizVersion, formats, and engines.

get graphvizVersion() → string

The version of Graphviz at runtime.

get formats() → string[]

The names of the Graphviz output formats supported at runtime.

get engines() → string[]

The names of the Graphviz layout engines supported at runtime.

render(input: string | Graph, options?: RenderOptions) → RenderResult

Renders the graph described by the input and returns the result as an object.

input may be a string in DOT syntax or a graph object.

This method does not throw an error if rendering failed, including for invalid DOT syntax, but it will throw for invalid types in input or unexpected runtime errors.

renderFormats(input: string | Graph, formats: string[], options?: RenderOptions) → MultipleRenderResult

Renders the graph described by the input for each format in formats and returns the result as an object. For a successful result, output is an object keyed by format.

input may be a string in DOT syntax or a graph object.

The format option is ignored.

This method does not throw an error if rendering failed, including for invalid DOT syntax, but it will throw for invalid types in input or unexpected runtime errors.

renderString(input: string | Graph, options?: RenderOptions) → string

Renders the input and returns the result as a string. Throws an error if rendering failed.

renderSVGElement(input: string | Graph, options?: RenderOptions) → SVGSVGElement

Convenience method that renders the input, parses the output, and returns an SVG element. The format option is ignored. Throws an error if rendering failed.

renderJSON(input: string | Graph, options?: RenderOptions) → object

Convenience method that renders the input, parses the output, and returns a JSON object. The format option is ignored. Throws an error if rendering failed.

RenderOptions

format?: string = "dot"

The Graphviz output format to render. For example, "dot" or "svg".

engine?: string = "dot"

The Graphviz layout engine to use for graph layout. For example, "dot" or "neato".

yInvert?: boolean = false

Invert y coordinates in output. This corresponds to the -y Graphviz command-line option.

reduce?: boolean = false

Reduce the graph. This corresponds to the -x Graphviz command-line option.

graphAttributes?: Attributes

Sets the default graph attributes. This corresponds the -G Graphviz command-line option.

nodeAttributes?: Attributes

Sets the default node attributes. This corresponds the -N Graphviz command-line option.

edgeAttributes?: Attributes

Sets the default edge attributes. This corresponds the -E Graphviz command-line option.

images?: ImageSize[]

Image sizes to use when rendering nodes with image attributes.

For example, to indicate to Graphviz that the image test.png has size 300x200:

viz.render("graph { a[image=\"test.png\"] }", {
  images: [
    { name: "test.png", width: 300, height: 200 }
  ]
});

RenderResult = SuccessResult | FailureResult

The result object returned by render.

MultipleRenderResult = MultipleSuccessResult | FailureResult

The result object returned by renderFormats.

SuccessResult

Returned by render if rendering was successful. errors may contain warning messages even if the graph rendered successfully.

status: "success"
output: string
errors: RenderError[]

MultipleSuccessResult

Returned by renderFormats if rendering was successful. errors may contain warning messages even if the graph rendered successfully.

status: "success"
output: { [format: string]: string }
errors: RenderError[]

FailureResult

Returned by render if rendering failed.

status: "failure"
output: undefined
errors: RenderError[]

RenderError

level?: "error" | "warning"
message: string

Graph

In addition to strings in DOT syntax, rendering methods accept graph objects.

Graph objects are plain JavaScript objects, similar to JSON Graph or the Dagre JSON serialization, but are specifically designed for working with Graphviz. Because of that, they use terminology from the Graphviz API (edges have a "head" and "tail", and nodes are identified with "name") and support features such as subgraphs, HTML labels, and default attributes.

Some example graph objects and the corresponding graph in DOT:

Empty directed graph

{}

digraph { }

Simple Undirected Graph

{
  directed: false,
  edges: [
    { tail: "a", head: "b" },
    { tail: "b", head: "c" },
    { tail: "c", head: "a" }
  ]
}

graph {
  a -- b
  b -- c
  c -- a
}

Attributes, Subgraphs, HTML Labels

{
  graphAttributes: {
    rankdir: "LR"
  },
  nodeAttributes: {
    shape: "circle"
  },
  nodes: [
    { name: "a", attributes: { label: { html: "<i>A</i>" }, color: "red" } },
    { name: "b", attributes: { label: { html: "<b>A</b>" }, color: "green" } }
  ],
  edges: [
    { tail: "a", head: "b", attributes: { label: "1" } },
    { tail: "b", head: "c", attributes: { label: "2", headport: "name" } }
  ],
  subgraphs: [
    {
      name: "cluster_1",
      nodes: [
        {
          name: "c",
          attributes: {
            label: {
              html: "<table><tr><td>test</td><td port=\"name\">C</td></tr></table>"
            }
          }
        }
      ]
    }
  ]
}

digraph {
  graph [rankdir="LR"]
  node [shape="circle"]
  a [label=<<i>A</i>>, color="red"]
  b [label=<<b>B</b>>, color="green"]
  a -> b [label="1"]
  b -> c:name [label="2"]
  subgraph cluster_1 {
    c [label=<<table><tr><td port="name">C</td></tr></table>>]
  }
}

name?: string
strict?: boolean = false
directed?: boolean = true
graphAttributes?: Attributes
nodeAttributes?: Attributes
edgeAttributes?: Attributes
nodes?: Node[]
edges?: Edge[]
subgraphs?: Subgraph[]

Attributes

[name: string]: string | number | boolean | HTMLString

HTMLString

html: string

Node

name: string
attributes?: Attributes

Edge

tail: string
head: string
attributes?: Attributes

Subgraph

name?: string
graphAttributes?: Attributes
nodeAttributes?: Attributes
edgeAttributes?: Attributes
nodes?: Node[]
edges?: Edge[]
subgraphs?: Subgraph[]

ImageSize

Specifies the size of an image used as a node's image attribute. See images.

width and height may be specified as numbers or strings with units: in, px, pc, pt, cm, or mm. If no units are given or measurements are given as numbers, points (pt) are used.

name: string

The name of the image. In addition to filenames, names that look like absolute filesystem paths or URLs can be used.

"example.png"
"/images/example.png"
"http://example.com/image.png"

Names that look like relative filesystem paths, such as "../example.png", are not supported.

width: string | number

The width of the image.

height: string | number

The height of the image.