elkjs is the successor of klayjs.
npm install elkjs
Releases and Versioning
Releases are partly synchronized with ELK's versions: the minor version number is always the same but the revision number may diverge. For instance, elkjs 0.3.0 equals the functionality of ELK 0.3.0 but elkjs 0.3.2 may be different from ELK 0.3.2. This is necessary as there may be fixes that solely concern elkjs and should be released independently of ELK.
The library consists of two main files:
elk-api.js: Provides the API and only the API.
elk-worker.js: Provides the code that actually knows how to lay out a graph. This is the file that is generated from ELK's Java code base using GWT.
Two further files are provided:
elk.bundled.js: A bundled version of the two previous files, ready to be dropped into a browser's
<script>tag. The file is processed by browserify and the
ELKis exposed as a global variable (if run in a browser).
main.js: Main file of the node.js module. Allows to conveniently write
require('elkjs')instead of composing the files from above.
A small example using node.js, for further use cases see the next section.
const ELK =const elk =const graph =id: "root"layoutOptions: 'elk.algorithm': 'layered'children:id: "n1" width: 30 height: 30id: "n2" width: 30 height: 30id: "n3" width: 30 height: 30edges:id: "e1" sources: "n1" targets: "n2"id: "e2" sources: "n1" targets: "n3"elk
You can use layout options to configure the layout algorithm.
For that you attach a
to the graph element that holds key/value pairs
representing the desired layout options.
See, for instance,
root in the example above.
It is possible to only use the suffix of a layout option:
algorithm instead of
However, if the suffix is not unique the layout option
may be ignored. To be save, you should always start the
layout options with the
A list of all options and further details of their exact effects is available in ELK's documentation.
It is possible to pass global layout options
as part of the
layout method's second argument.
The options are then applied to every graph element
unless the element specifies the option itself:
ELK's constructor accepts an object
with layout options that is used with every
layout call that does not specify layout options:
const elk =defaultLayoutOptions: ...
Since laying out diagrams can be a time-consuming job (even for the computer), and since we don't want to freeze your UI, Web Workers are supported out of the box. The following examples illustrate how the library can be used either with and without a Web Worker.
const ELK =// without web workerconst elk =elk
const ELK =// with web workerconst elk =workerUrl = './node_modules/elkjs/lib/elk-worker.min.js'elk
Note that node.js doesn't come with a web worker out of the box.
Thus, we have to use a library for it and selected
webworker-threads as default.
Any other library that provides the standard Web Worker methods should be fine though.
The package is not installed automatically to avoid
the unnecessary dependency for everyone who is not
interested in using a web worker.
A warning is raised if one requests a web worker
without having installed the package.
elkjs falls back to the non-Web Worker version in that case.
<!-- use elk-api.js here! -->
The elkjs library provides a single object: the
ELK has a constructor that can be used
to construct it:
new ELK(options)- the
ELKcan be fed with options, all of which are optional:
defaultLayoutOptions- an object with default layout options specified as key/value pairs that are used if no further layout options are passed to the
layout(graph, options)method (see below). Default:
algorithms- an array of algorithm ids (only the suffix). Default:
[ 'layered', 'stress', 'mrtree', 'radial', 'force', 'disco' ]. Note that the
randomlayouters are always included.
workerUrl- a path to the
elk-worker.jsscript. As a consequence the
ELKwill use a Web Worker to execute the layout. Default:
Apart from that the
ELK offers the following methods:
graph- the graph to be laid out in ELK JSON. Mandatory!
options- a configuration object. Currently its sole purpose is to pass global layout options. That is, layout options that are applied to every graph element unless the element specifies the option itself. Optional.
- returns a
Promise, which passes either the laid out graph on success or a (hopefully helpful) error on failure.
- returns an array of of known layout options. For each options additional information
such as its
- returns an array of of known layout options. For each options additional information such as its
- returns an array of registered layout algorithms (see above) alongside further information about each algorithm.
- returns an array of registered layout categories.
terminateWorker()- in case a Web Worker is used, the worker's
terminate()method is called.
The three methods starting with
known basically return information
that, in the Java world, would be retrieved from the
For building, a checkout of the ELK repository is required and should be located in the same directory as the checkout of this repository.
npm installnpm run build
Afterwards you can find the created files in the