Renders a Graphviz graph from the text source to SVG.
MIT License
WebComponents for rendering a Graphviz graph and for editing its source script with syntax highlighting. Uses @hpcc-js/wasm to generate the graph image in the web browser using WASM. See it working on-line!
Features:
Related tools:
Render a graph:
<graphviz-graph graph="
digraph G {
main -> parse -> execute;
main -> cleanup;
}
"></graphviz-graph>
<script defer src=https://unpkg.com/[email protected]/dist/graph.min.js></script>
Show a script editor and render the edited content to a graph:
<graphviz-script-editor id=source value="
digraph G {
main -> parse -> execute;
main -> cleanup;
}
"></graphviz-script-editor>
<graphviz-graph id=graph></graphviz-graph>
<script type=module>
import 'https://unpkg.com/[email protected]/dist/index.min.mjs'
document.getElementById('source').addEventListener('update', event => {
document.getElementById('graph').graph = event.detail
})
</script>
Make sure that you have installed Node.js. Use your favourite package manager (NPM, Yarn or PNPM) to add the graphviz-webcomponent
module to your project. Add -D
on the command line if you use a bundler:
npm i graphviz-webcomponent
yarn add graphviz-webcomponent
pnpm i graphviz-webcomponent
If you write a plain HTML page, insert the graphviz-webcomponent
script pointing either to CDN or to the local filesystem:
<script src=https://unpkg.com/[email protected]/dist/index.min.js></script>
<script src=node_modules/graphviz-webcomponent/dist/index.min.js></script>
If you're going to use the script from a URL different from unpkg, or compile it to your application scripts, and you won't take one of the scripts with the bundled Web worker renderer, you will have to set the rendererUrl
property accordingly. See the configuration for more information.
Distributed scripts:
index.min.js
- both graphviz-graph
and graphviz-script-editor
elementsindex-bundled.min.js
- both graphviz-graph
and graphviz-script-editor
elements and the Web worker renderergraph.min.js
- the graphviz-graph
elementgraph-bundled.min.js
- the graphviz-graph
element and the Web worker rendererscript-editor.min.js
- the graphviz-script-editor
elementrenderer.min.js
- web worker for the graphviz-graph
elementThe first three scripts are available as ES6 modules with the file extension .mjs
too. They export the HTML elements as classes.
The custom element graphviz-graph
generates an SVG and displays it in its shadow root.
<graphviz-graph graph="..." scale="..."></graphviz-graph>
The attribute graph
supplies the graph script in the Graphviz format. Whenever the graph
attribute changes, the element content will be re-generated and re-rendered. If this attribute is empty, the element content will be empty. If generating of the image fails, the element will display an error message.
The attribute scale
sets the "zoom" level for the SVG content. It has to be convertible to a real number greater than 0
. Values in the interval (0;1>)
decrease the image size, values greater than 1
increase it. The default value is 1
, which means the original size. The value can be convertent to percents of the original size by multiplying by 100
.
The property graphCompleted
returns a promise with the result of the last rendering. If the rendering hasn't been finished yet, the promise will be pending. Whenever the graphviz-graph
is being re-rendered again, the property graphCompleted
will return a new promise. If rendering succeeds, the promise will be resolved with a string containing the SVG content. If rendering fails, the promise will be resolved with am object { message }
containing the error message. The property graphCompleted
is an alternative to waiting for the event render
.
Whenever the SVG image inside the graphviz-graph
element is successfully updated, the custom event render
with the SVG source as details will be triggered on the element. If the rendering fails, the custom event error
with the Error
instance as details will be triggered.
The method tryGraph(graph: string): Promise<string>
can be called to conditionally set the graph
attribute. If rendering the graph script succeeds, the input value will be set to the graph
attribute, the graphviz-graph
element will be updated (including triggering the render
event) and the Promise will be resolved with the output SVG. If rendering the graph script fails, the graphviz-graph
element will remain unchanged (no error
event triggered) and the Promise will be rejected with the error.
The graphviz-graph
element uses a Web Worker to perform the rendering in the background and WASM to improve the computation performance. The external script is loaded from a URL, which can be customized. The default is:
graphvizWebComponent = {
rendererUrl: 'https://unpkg.com/[email protected]/dist/index.min.js',
delayWorkerLoading: false
}
The global object graphvizWebComponent
can be set before the graphviz-webcomponent
scripts (index.min.js
or graph.min.js
) are imported to change the defaults. Changing the properties after the scripts are loaded will have no effect.
If you set graphvizWebComponent.delayWorkerLoading
to true, the web worker will be downloaded when the first graphviz-graph
element will be inserted to the page.
If you want to enforce only local resources, you can change the URLs to relative paths within your project by setting the global graphvizWebComponent
object, for example:
<script>
graphvizWebComponent = {
rendererUrl: '../node_modules/graphviz-webcomponent/dist/renderer.min.js'
}
</script>
Configuring the rendererUrl
via graphvizWebComponent
can be avoided, if you don't need to load the renderer script in the background. Choose one of the scripts with -bundled
in their name then:
<script src=https://unpkg.com/[email protected]/dist/index-bundled.min.js></script>
<script src=node_modules/graphviz-webcomponent/dist/graph-bundled.min.js></script>
import 'graphviz-webcomponent/bundled'
The custom element graphviz-script-editor
shows a graph source with syntax highlighting and allows its editing.
<graphviz-script-editor value="..." tab="..." class="..."></graphviz-graph>
The attribute value
accepts the graph script in the Graphviz format. Whenever this attribute changes, the editor will be re-rendered. The value
attribute reflects the immediate changes made in the editor.
The attribute tab
can specify characters inserted when the Tab
key is pressed. It is two spaces (" "
) by default.
The attribute class
controls features by special class names:
line-numbers
will add line numbers to the left border of the editor.match-braces
will show the second brace brace, when the first one is hovered above.rainbow-braces
will show pairs of braces with different colours.Whenever the content of the editor changes, the custom event update
with the source script as details will be triggered on the element. The attribute value
will contain the latest editor content.
The language support in the VS Code editor can offer auto-completion and hover information for custom elements. To enable this feature for custom elements in this package, insert the following property to settings.json
:
"html.customData": ["node_modules/graphviz-webcomponent/dist/html-custom-data.json"]
You will need to restart the VS Code to have this change applied.
If your IDE accepts the custom elements manifest, you will find it packaged at node_modules/graphviz-webcomponent/dist/custom-elements.json
.
Copyright (c) 2020-2023 Ferdinand Prantl
Licensed under the MIT license.