Packages
In 5.x the Toolkit is delivered as a set of packages, rather than as a monolith like 2.x. This page provides a list of all the packages (including Community edition packages, as the Toolkit still has a dependency on the Community edition).
On this page any reference to the "vanilla" renderer means the Toolkit without a library integration, using the Toolkit's own template engine.
At the bottom of the page there is a section detailing how to use packages with ES5.
Quick Reference
Here we provide an overview of the packages you will need, depending on your requirements.
Vanilla
, throughout the documentation, refers to the case that you are not using a library integration such as Angular/React/Vue/Svelte. Each row in this first table identifies the base import you will need, along with the optional import required if you wish to support drag/drop of new vertices onto the canvas.
Note that current versions of the Toolkit offer a browser-ui-vanilla
package and also a browser-ui-vanilla-2
package. The difference between these is in the underlying template renderer: the template renderer in the vanilla-2
package does not use eval
or with
, two expressions that in certain sandboxed environments such as Salesforce are not supported. Additionally, vanilla-2
's template syntax uses a "handlebars" style for variable interpolation ({{ ... }}
) instead of the original template engine's ${...}
syntax. This original syntax would preclude you from embedding ES6 string literals.
From version 6.0.0 onwards (for which a release date has not yet been set) the current browser-ui-vanilla-2
package will be renamed to browser-ui-vanilla
and the existing browser-ui-vanilla
package will no longer be available. It is recommended that all users of vanilla Toolkit use the browser-ui-vanilla-2
package.
Basic setup
Library | Base import | Drag/drop |
---|---|---|
Vanilla | @jsplumbtoolkit/browser-ui-vanilla | @jsplumbtoolkit-drop |
Vanilla 2 | @jsplumbtoolkit/browser-ui-vanilla-2 | @jsplumbtoolkit-drop |
Angular | @jsplumbtoolkit/browser-ui-angular | @jsplumbtoolkit-angular-drop |
React | @jsplumbtoolkit/browser-ui-react | @jsplumbtoolkit-react-drop |
Vue 2 | @jsplumbtoolkit/browser-ui-vue2 | @jsplumbtoolkit-vue2-drop |
Vue 3 | @jsplumbtoolkit/browser-ui-vue3 | @jsplumbtoolkit-vue3-drop |
Svelte | @jsplumbtoolkit/browser-ui-svelte | @jsplumbtoolkit-drop (no specific Svelte drop package required) |
Layouts
By default, the Toolkit ships with the Absolute layout. If you wish to use some other layout, you will need to import it separately.
Layout | Package | Description |
---|---|---|
ForceDirected | @jsplumbtoolkit/layout-force-directed | Provides a force directed layout |
Hierarchy | @jsplumbtoolkit/layout-hierarchy | Places vertices hierarchically, using a modified Sugiyama method |
Hierarchical | @jsplumbtoolkit/layout-hierarchical | The classic "org chart" layout |
Balloon | @jsplumbtoolkit/layout-hierarchical | Groups vertices into clusters |
Circular | @jsplumbtoolkit/layout-circular | Arranges vertices in a circle |
Spring | @jsplumbtoolkit/layout-spring | Provides a force directed layout (deprecated; use ForceDirected instead) |
Connectors
By default, the Toolkit ships with the Straight connector. If you wish to use some other connector, you will need to import it separately.
Layout | Package | Description |
---|---|---|
Bezier | @jsplumb/connector-bezier | Provides a bezier curve connector |
StateMachine | @jsplumb/connector-bezier | A connector with a slight curve (a quadratic Bezier) |
Orthogonal | @jsplumbtoolkit/connector-orthogonal | The classic "flowchart" connector |
Plugins
There are a number of plugins you can install on an instance of the Surface. Each of these is supplied in its own package:
Name | Package | Description |
---|---|---|
lasso | @jsplumbtoolkit/browser-ui-plugin-lasso | Provides a means to select groups of vertices with the mouse |
drawingTools | @jsplumbtoolkit/browser-ui-plugin-drawing-tools | Offers the ability to alter the size of vertices with the mouse |
miniview | @jsplumbtoolkit/browser-ui-plugin-miniview | Provides a 'miniview' - a small view of all the vertices in its associated Surface |
panButtons | @jsplumbtoolkit/browser-ui-plugin-pan-buttons | Provides buttons around the perimeter of a Surface that can be used to nudge the canvas. |
ui-states | @jsplumbtoolkit/browser-ui-plugin-ui-states | Provides a means to change the appearance of sets of vertices according to their 'state |
dragGroups | @jsplumbtoolkit/browser-ui-plugin-drag-groups | Provides a means to manage logical drag groups |
background | @jsplumbtoolkit/browser-ui-plugin-background | Provides a means to set backgrounds on a Surface, either as a single image or tiled |
Core
@jsplumbtoolkit/core
Contains the core Toolkit code. Has a dependency on @jsplumb/util
for various helper functions, but is renderer agnostic.
@jsplumbtoolkit/templates
Contains the renderer-agnostic code for the templates that the vanilla renderer uses. These are packaged separately from the vanilla renderer's implementation so that at some stage in the future they can be used to support a headless renderer. This is not a package you'll need to manually import, unless you do not use a bundler.
Layouts
In 5.x only the Absolute
and AbsoluteBacked
layouts are shipped in the core (they are shipped inside the @jsplumbtoolkit/core
package as they are renderer agnostic). The other layouts have been extracted to their own packages.
@jsplumbtoolkit/layout-force-directed
Provides a layout that uses a force directed algorithm. This is a newer version of the original Spring
layout, and users of the Spring layout are encouraged to switch to this.
@jsplumbtoolkit/layout-spring
Provides the Spring
layout.
@jsplumbtoolkit/layout-circular
Provides the Circular
layout.
@jsplumbtoolkit/layout-hierarchical
Provides the Hierarchical
layout and also the Balloon
layout (since Balloon
layout extends Hierarchical
layout). Also provides the AbstractHierarchicalLayout
class, which is a base class that other "hierarchical" layouts can extend.
@jsplumbtoolkit/layout-hierarchy
A newer version of the Hierarchical
layout, with improved positioning and handling of loops.
Rendering
At the core of the Toolkit's rendering is still the Surface
widget, which you'll now find in the @jsplumbtoolkit/browser-ui
package. One of the things we've concentrated on in this new release is the fact that the specific mechanism used by the Surface to render your dataset - that of a single DOM element representing each vertex, and a single SVG representing each edge - is not necessarily the only satisfactory means to render the UI: there are plenty of scenarios where, for instance, a single SVG element containing all the vertices and edges would suffice. Another option is of rendering to a single canvas element. We're keen to explore these ideas in the coming months and with 5.x we've got a solid foundation to do so.
To assist with this process of exploring alternative renderers, we've introduced the browser-ui
prefix to the current UI packages. Whenever you see browser-ui
as part of a package name it means that it pertains to the renderer that uses a single DOM element per vertex and a single SVG element per edge.
@jsplumbtoolkit/browser-ui
This package contains the core rendering functionality but no template engine, meaning for those using an integration such as browser-ui-angular
your bundle does not pull in the templates which only the vanilla renderer requires. You'll use this package in your imports, regardless of the specific renderer you use, as the specific renderers are a very thin wrapper around this package.
@jsplumbtoolkit/browser-ui-vanilla-2
This package is the package to use when you're not using a library integration; it is basically the equivalent of the "jsplumbtoolkit" package in 2.x. This package has been available since 5.6.0; users of 5.x versions prior to 5.6.0 will use the browser-ui-vanilla
package discussed below.
@jsplumbtoolkit/browser-ui-vanilla
This is the original vanilla renderer. Since version 5.6.0 this package has been superseded by browser-ui-vanilla-2
, but will still be supported for all 5.x versions.
@jsplumbtoolkit/browser-ui-anim
Provides a few basic animation functions for use with a Surface.
@jsplumbtoolkit/browser-ui-templates-2
Contains the template engine that both @jsplumbtoolkit/browser-ui-vanilla-2
and @jsplumbtoolkit/dialogs-2
use. This import will be automatically pulled in as needed, unless you're not using a bundler.
@jsplumbtoolkit/browser-ui-templates
Contains the template engine that both @jsplumbtoolkit/browser-ui-vanilla
and @jsplumbtoolkit/dialogs
use. This import will be automatically pulled in as needed, unless you're not using a bundler.
@jsplumbtoolkit/browser-ui-plugin-miniview
Provides the miniview.
@jsplumbtoolkit/browser-ui-plugin-lasso
Provides the lasso tool.
@jsplumbtoolkit/browser-ui-plugin-drawing-tools
Provides the drawing tools plugin.
@jsplumbtoolkit/browser-ui-plugin-pan-buttons
Provides the pan buttons - the buttons that appear at the perimeter of the Surface's viewport, allowing the user to nudge the canvas.
@jsplumbtoolkit/browser-ui-plugin-active-filtering
Provides the "active filtering" functionality - the ability to filter connection drop targets at drag start.
@jsplumbtoolkit/browser-ui-plugin-state
Provides utilities to save/restore the state of some Surface widget to local storage.
@jsplumbtoolkit/browser-ui-plugin-background
Provides a means to set a background on a Surface, either as a single image, or as a set of tiles.
Community edition
The Toolkit in 5.x still has a dependency on the Community edition, generally without your knowledge, for internal purposes, but occasionally you will need to reference something in the Community edition. Also if your application is written in ES5 then you will need to manually import various Community edition packages.
Over time we're going to be looking at ways of reducing the number of Community edition packages you need to reference when working with the Toolkit.
@jsplumb/util
Provides a set of helper functions that are used extensively throughout the Toolkit and may perhaps be of some use to you.
@jsplumb/common
This is a package you will likely want to use. It contains the shared interfaces defining such things as anchor specifications, anchor locations, connector specifications, endpoint specifications, etc. It also exports a few basic constants that may be of use.
@jsplumb/core
This is the Community edition core. This package contains all of the Endpoints, such as Dot
, Rectangle
, Blank
, as well as the base Overlay
class and its implementations (LabelOverlay
etc). In addition it contains the StraightConnector
class. If you want to reference these things in a type safe way in your view (rather than simply as a string representing the name of the thing) then you'll need to import them from @jsplumb/core
.
See also the Connector packages section below for details of a couple of other Community packages you may need.
Connectors
In 5.x the Toolkit only ships with the Straight
connector. To use some other connector you'll need to import the appropriate package.
@jsplumb/connector-bezier
Provides the Bezier
and StateMachine
connectors. Note the package name uses @jsplumb
as the prefix - these are provided by the underlying Community edition.
@jsplumb/connector-flowchart
Included here for completeness, but this Community edition connector is supplanted by the Toolkit's @jsplumbtoolkit/connector-orthogonal
connector.
@jsplumbtoolkit/connector-orthogonal
An extension of the original Flowchart
connector with a better name and support for user editing of the path. For users of 2.x who have Flowchart
connectors in their application, you should import this package and use Orthogonal
as your connector type.
Edge editors
These used to all be provided in a single package - jsplumbtoolkit-connector-editors.tgz
. In 5.x we've split these out into the base functionality in one package, and a package for each supported connector type.
@jsplumbtoolkit/connector-editors
This is the base functionality. A connector specific implementation will import this.
@jsplumbtoolkit/connector-editors-orthogonal
Connector editors for the Orthogonal
connector. This package will automatically import @jsplumbtoolkit/connector-orthogonal
.
@jsplumbtoolkit/connector-editors-bezier
Connector editors for the Bezier
and StateMachine
connectors. This package will automatically import @jsplumb/connector-bezier
.
Utilities
Most of these packages were already delivered as external packages in 2.x. In 5.x their package names have been changed but their function remains the same.
@jsplumbtoolkit/dialogs
Provides the lightweight dialogs originally created for use in the Toolkit demonstrations. As with the browser-ui-vanilla
package, since 5.6.0 this package has been superseded, in this case by dialogs-2
, but will be supported for all 5.x versions.
@jsplumbtoolkit/dialogs-2
A port of the lightweight dialogs originally created for use in the Toolkit demonstrations, available from 5.6.0 onwards. This package differs from dialogs
in the underlying template engine it uses: dialogs-2
uses templates-2
, whereas dialogs
uses templates
.
@jsplumbtoolkit/drop
Provides the drag/drop manager.
@jsplumbtoolkit/labels
Provides various utilities for working with labels.
@jsplumbtoolkit/search
Provides a reverse text search index.
@jsplumbtoolkit/print
Provides support for server side printing (using node).
@jsplumbtoolkit/copy-paste
Provides support for copy/paste of items. See the documenation for more information.
@jsplumbtoolkit/test-support
These are a set of utilities we use in the Toolkit's own unit tests, and their inclusion in this list comes with the caveat that they are not necessarily sufficiently fully featured or useful for other scenarios. We're keen for them to become a first class part of the Toolkit offering, though, so all feedback is welcome.
Integrations
@jsplumbtoolkit/browser-ui-angular
Provides Angular integration. At the time of writing this has been tested up to Angular 13.
@jsplumbtoolkit/browser-ui-angular-drop
Provides Angular integration with the drop manager. At the time of writing this has been tested up to Angular 13.
@jsplumbtoolkit/browser-ui-react
Provides React integration. Requires React 17 or greater. Tested on 17 and 18.
@jsplumbtoolkit/browser-ui-react-drop
Provides React integration with the drop manager. Requires React 17 or greater. Tested on 17 and 18.
@jsplumbtoolkit/browser-ui-vue2
Provides Vue2 integration.
@jsplumbtoolkit/browser-ui-vue2-drop
Provides Vue2 integration with the drop manager.
@jsplumbtoolkit/browser-ui-vue3
Provides Vue3 integration.
@jsplumbtoolkit/browser-ui-vue3-drop
Provides Vue3 integration with the drop manager.
@jsplumbtoolkit/browser-ui-svelte
Provides Svelte 3integration.
Using packages with ES5
If you're writing your application in ES5 then you will need to use the UMD
bundles of each of the Toolkit's packages, and you'll also need to include all of the Toolkit's internal dependencies yourself.
For each package, we supply 3 Javascript files inside the package's .tgz. For instance, for @jsplumbtoolkit/core
, we provide:
jsplumbtoolkit.core.es.js
- The package bundled as an ES modulejsplumbtoolkit.core.cjs.js
- The package bundled as a CommonJS modulejsplumbtoolkit.core.umd.js
- The package bundled as a UMD module.
The UMD
module is the one to use when you're using ES5: it registers the package in the browser with a global name that your scripts can use to access it.
UMD Import examples
This is the bare minimum set of imports you need to get an instance of the Toolkit up and render it to some element:
<script src="node_modules/@jsplumb/util/js/jsplumb.util.umd.js"></script>
<script src="node_modules/@jsplumb/common/js/jsplumb.common.umd.js"></script>
<script src="node_modules/@jsplumb/core/js/jsplumb.core.umd.js"></script>
<script src="node_modules/@jsplumb/browser-ui/js/jsplumb.browser-ui.umd.js"></script>
<script src="node_modules/@jsplumbtoolkit/core/js/jsplumbtoolkit.core.umd.js"></script>
<script src="node_modules/@jsplumbtoolkit/templates/js/jsplumbtoolkit.templates-2.umd.js"></script>
<script src="node_modules/@jsplumbtoolkit/browser-ui/js/jsplumbtoolkit.browser-ui.umd.js"></script>
<script src="node_modules/@jsplumbtoolkit/browser-ui-templates-2/js/jsplumbtoolkit.browser-ui-templates-2.umd.js"></script>
<script src="node_modules/@jsplumbtoolkit/browser-ui-vanilla-2/js/jsplumbtoolkit.browser-ui-vanilla-2.umd.js"></script>
These imports are written as if the html file is in the same directory as node_modules
. You may need to change the base url for the imports to match your setup.
Importing the UMD modules like this will result in a global member being added for each import module. The name for each of these global variables is given below.
As an example, if you wanted to create an instance of the Toolkit:
var toolkit = jsPlumbToolkitBrowserUIVanilla2.newInstance()
UMD Global names
This is the list of global names for each package.
package | global name |
---|---|
@jsplumbtoolkit/core | jsPlumbToolkit |
@jsplumbtoolkit/templates | jsPlumbToolkitTemplates |
@jsplumbtoolkit/templates-2 | jsPlumbToolkitTemplates2 |
@jsplumbtoolkit/layout-spring | jsPlumbToolkitLayoutSpring |
@jsplumbtoolkit/layout-force-directed | jsPlumbToolkitLayoutForceDirected |
@jsplumbtoolkit/layout-circular | jsPlumbToolkitLayoutCircular |
@jsplumbtoolkit/layout-hierarchical | jsPlumbToolkitLayoutHierarchical |
@jsplumbtoolkit/layout-hierarchy | jsPlumbToolkitLayoutHierarchy |
@jsplumbtoolkit/browser-ui | jsPlumbToolkitBrowserUI |
@jsplumbtoolkit/browser-ui-vanilla | jsPlumbToolkitBrowserUIVanilla |
@jsplumbtoolkit/browser-ui-vanilla-2 | jsPlumbToolkitBrowserUIVanilla2 |
@jsplumbtoolkit/browser-ui-anim | jsPlumbToolkitBrowserUIAnim |
@jsplumbtoolkit/browser-ui-templates | jsPlumbToolkitBrowserUITemplates |
@jsplumbtoolkit/browser-ui-templates-2 | jsPlumbToolkitBrowserUITemplates2 |
@jsplumbtoolkit/browser-ui-plugin-miniview | jsPlumbToolkitBrowserUIPluginMiniview |
@jsplumbtoolkit/browser-ui-plugin-lasso | jsPlumbToolkitPluginLasso |
@jsplumbtoolkit/browser-ui-plugin-drawing-tools | jsPlumbToolkitPluginDrawingTools |
@jsplumbtoolkit/browser-ui-plugin-pan-buttons | jsPlumbToolkitPanButtons |
@jsplumbtoolkit/browser-ui-plugin-active-filtering | jsPlumbToolkitPluginActiveFiltering |
@jsplumbtoolkit/browser-ui-plugin-state | jsPlumbToolkitPluginState |
@jsplumb/core | jsPlumb |
@jsplumb/common | jsPlumbCommon |
@jsplumb/util | jsPlumbUtil |
@jsplumb/browser-ui | jsPlumbBrowserUI |
@jsplumb/connector-bezier | jsPlumbConnectorBezier |
@jsplumbtoolkit/connector-orthogonal | jsPlumbToolkitConnectorOrthogonal |
@jsplumbtoolkit/connector-editors-bezier | jsPlumbToolkitConnectorEditorsBezier |
@jsplumbtoolkit/connector-editors-orthogonal | jsPlumbToolkitConnectorEditorsOrthogonal |
@jsplumbtoolkit/dialogs | jsPlumbToolkitDialogs |
@jsplumbtoolkit/dialogs-2 | jsPlumbToolkitDialogs2 |
@jsplumbtoolkit/drop | jsPlumbToolkitDrop |
@jsplumbtoolkit/labels | jsPlumbToolkitLabels |
@jsplumbtoolkit/search | jsPlumbToolkitSearch |
@jsplumbtoolkit/print | jsPlumbToolkitPrint |
@jsplumbtoolkit/copy-paste | jsPlumbToolkitCopyPaste |