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 theinstance
function.The
graphvizVersion
,formats
, andengines
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 constantsgraphvizVersion
,formats
, andengines
.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.
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
. 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[]
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.