repository·v3·Indexed 26 days ago
https://github.com/mdaines/viz-jsA collection of JavaScript packages providing WebAssembly-powered Graphviz capabilities. It enables rendering complex graph diagrams (such as DOT files) as SVG elements or strings in the browser. Key packages include @viz-js/viz for the core Graphviz engine, @viz-js/dot2svg for converting DOT strings to SVG, and @viz-js/lang-dot for CodeMirror language support.
@viz-js/viz, provides a WebAssembly build of Graphviz with a JavaScript wrapper, allowing you to render graph diagrams (such as DOT files) directly into web pages as SVG elements.You can install the Viz.js packages using npm:
npm install @viz-js/viznpm install @viz-js/lang-dotViz.js provides a WebAssembly build of Graphviz with a JavaScript wrapper. To use it, import the @viz-js/viz package and call Viz.instance(). This function returns a Promise that resolves to a Viz class instance. Once the instance is available, you can use methods like renderSVGElement to render graph strings (e.g., DOT language) into SVG elements. The returned instance can be reused to render multiple graphs.
import * as Viz from "@viz-js/viz";
Viz.instance().then(viz => {
const svg = viz.renderSVGElement("digraph { a -> b }");
document.getElementById("graph").appendChild(svg);
});To render a graph diagram, import * as Viz from @viz-js/viz. Use Viz.instance() to get the initialized WebAssembly instance, then call renderSVGElement(dotString) on that instance to generate an SVG element. You can then append this element to the DOM.
import * as Viz from "@viz-js/viz";
Viz.instance().then(viz => {
document.body.appendChild(viz.renderSVGElement("digraph { a -> b }"))
});Use the dot2svg function from the @viz-js/dot2svg package to convert DOT language strings into SVG strings. The function returns a Promise that resolves with the generated SVG content.
import { dot2svg } from "@viz-js/dot2svg";
dot2svg("digraph { a -> b }")
.then(svg => {
// parse, insert into document, etc.
})When calling rendering methods, you can pass a RenderOptions object to customize the output:
| Property | Type | Description |
|---|---|---|
format | string | Graphviz output format (e.g., "svg", "png", "dot"). |
engine | string | Layout engine to use (e.g., "dot", "neato"). |
yInvert | boolean | Invert y coordinates (corresponds to -y flag). |
reduce | boolean | Reduce the graph (corresponds to -x flag). |
graphAttributes | Attributes | Default graph attributes (corresponds to -G flag). |
nodeAttributes | Attributes | Default node attributes (corresponds to -N flag). |
edgeAttributes | Attributes | Default edge attributes (corresponds to -E flag). |
images | ImageSize[] | Array of image sizes for nodes using image attributes. |
Example for specifying image sizes:
viz.render("graph { a[image=\"test.png\"] }", {
images: [
{ name: "test.png", width: 300, height: 200 }
]
});The dot2svg function asynchronously converts a DOT language source string into an SVG string. It uses the underlying @viz-js/viz instance to perform the rendering.
Parameters:
src (string): The DOT source code to be rendered.options (object, optional): An options object.engine (string, optional): Specifies the rendering engine to use.Returns:
Promise<string>: A promise that resolves to the rendered SVG string.The Viz class is the primary interface for rendering Graphviz input. It requires a module (the WebAssembly/Emscripten module) passed to the constructor.
Key rendering methods:
render(input, options): Returns a result object containing the status and output. If successful, the output is mapped to the requested format.renderString(src, options): A convenience method that returns the rendered string directly. It throws an error if the rendering status is not success.renderSVGElement(src, options): Returns a DOM Element representing the rendered SVG. Supports a trustedTypePolicy option for environments using Trusted Types.renderJSON(src, options): Returns the rendered output parsed as a JavaScript object (when the format is json).renderFormats(input, formats, options): Renders the input into multiple specified formats simultaneously.Common options include:
format: The output format (e.g., 'svg', 'png', 'json'). Defaults to 'dot' if not specified in render (though usually, you want to specify the target format).engine: The Graphviz layout engine to use (e.g., 'dot', 'neato', 'fdp'). Defaults to 'dot'.trustedTypePolicy: An object with a createHTML method, used for sanitizing SVG strings in secure environments.renderFormats to render the same input into multiple Graphviz output formats simultaneously. If successful, it returns a MultipleSuccessResult where the output is an object keyed by the format name.The render method takes a DOT string or a Graph object and returns a RenderResult. This result is an object that indicates whether the rendering was a success or a failure and contains the output and any errors (warnings or errors).
Note: render does not throw for invalid DOT syntax, but it will throw for invalid input types or unexpected runtime errors.
Viz provides convenience methods that handle both rendering and parsing, throwing an error if the process fails:
renderSVGElement(input, options): Returns an SVGSVGElement. The format option is ignored.renderJSON(input, options): Returns a parsed JSON object. The format option is ignored.renderString(input, options): Returns the raw output as a string. Throws if rendering fails.The Viz instance provides getters to inspect the capabilities of the loaded Graphviz module:
graphvizVersion: Returns the version of Graphviz being used.formats: Returns a list of available output formats (devices) supported by the module.engines: Returns a list of available layout engines supported by the module.