JointJS: an SVG diagramming library for production editors

Who JointJS is for and what it replaces

JointJS targets teams building diagram editors as part of a larger application: flowchart and process editors, BPMN modelers, data modeling tools, org chart builders, SCADA and HMI dashboards, and node-based AI pipeline builders. The README lists those domains explicitly. The common thread is that the diagram is data, not decoration. You need to know which element connects to which, find predecessors and neighbors, embed elements inside containers, and serialize the whole thing to JSON.

That distinguishes it from a canvas drawing library. A drawing library gives you pixels and leaves the graph to you. JointJS ships a graph model with traversal methods (dfs, bfs, find neighbors, elements at point), hierarchical relationships between elements, and import and export to JSON. If your editor needs to answer "what feeds into this node", the model is already there.

It is also framework-agnostic. The README states that React has first-class, native support through JointJS for React, while Angular, Vue, Svelte and Salesforce Lightning have integration guides and examples. There is no requirement to adopt a particular component framework to use the core library.

The MVC split behind JointJS diagrams

JointJS is built around an MVC architecture rendered to SVG. The model is a graph object holding elements and links, each with custom properties and data you define. The view layer draws that model as SVG DOM nodes, which is why elements can be styled with CSS and why text stays selectable and crisp at any zoom level. Because the output is SVG rather than a bitmap, every element is a real DOM node you can attach events to.

Links are the part with the most machinery. A link has anchors, connection points, vertices, routers and connectors, all configurable. Routers decide the path between two elements, connectors decide how corners and curves are drawn, and anchors decide where the link attaches. The repository publishes a separate @joint/router-avoid package, and the examples directory contains an avoid-router-ts example, so obstacle-avoiding routing is a distinct concern rather than something baked into the core.

Interactivity is event driven. The README describes the library as highly event driven, meaning you react to changes inside the diagram rather than polling. On top of that sit element and link tools (buttons, status icons, handles for reshaping links) and highlighters for visual emphasis. Ports are configurable in both appearance and position, either distributed around a shape or placed manually. That port system is what makes connection-heavy editors practical: users drag from a specific point on a node, and the model records which port was used.

Installing @joint/core and drawing a first diagram

The repository is a Yarn workspace monorepo, and the packages published from it include @joint/core, @joint/layout-directed-graph, @joint/layout-msagl and @joint/router-avoid. For application code you consume the published packages rather than cloning the repository. The README points to the getting started guide at docs.jointjs.com for that path.

If you do want to work on the library itself, the README requires Node version 22.14.0 and Yarn 2.0.0 or later, and notes that Volta reads the restriction from package.json. The setup sequence is clone, install, build the distribution files:

git clone https://github.com/clientIO/joint.git
cd joint
yarn install
yarn run dist

After that, the README says you can browse the example applications, which combine functionality from multiple JointJS packages, from the examples directory. The core package demos live under packages/joint-core/demo, and most of them run by opening index.html directly in a browser.

For a first real use, the README gives this MCP endpoint for AI coding agents:

https://mcp.jointjs.com/mcp

Connecting an MCP-compatible agent to that endpoint exposes search_docs and search_demos, so the agent queries the official documentation and demos instead of guessing at the API. That is a concrete advantage when you are writing your first graph: the API surface is large, and an agent working from the real docs is less likely to invent method names.

The repository also documents the test and lint entry points, all run through Yarn workspaces:

yarn run test
yarn run test-server
yarn run test-client
yarn run test-ts
yarn run lint

The test script fans out to every workspace, and the README notes separate commands for server-side, client-side and TypeScript tests. If you are evaluating the library rather than contributing, the example applications are the faster route: each has its own README with instructions.

What the open source package does not include

The most important limitation is licensing scope, not code quality. The README states plainly that the open-source library covers core diagramming, and that JointJS+ adds production-ready plugins: stencils, inspectors, toolbars, advanced layouts, import and export, and professional demo apps including source code. JointJS for React is also listed under the commercial version.

That means a team can build a working editor on the open source core and still hit a wall when it needs an inspector panel bound to element properties, a stencil palette, or Visio BPMN import and export. The README mentions Visio BPMN import and export in its BPMN use case row, and the commercial section lists import/export among the plugins. Anyone planning a BPMN modeler should confirm which side of that line each capability falls on before choosing the library.

The repository is not archived and the last push was on 2026-09-22, so the project is not dormant. Releases are managed with changesets, and the recent releases include @joint/core 4.3.3, @joint/react 4.3.6 and @joint/router-avoid 4.3.3, all dated 2026-09-04. Note that the root package.json carries version 4.3.1 while the published @joint/core release is 4.3.3; the root is a private workspace manifest, not the published artifact, so pin the package version rather than the repository version.

Browser support is a stated list, not a range: the latest Chrome including mobile, latest Firefox, latest Safari including mobile, latest Edge and latest Opera. There is no Internet Explorer entry and no statement about older browser versions. If your product must run in an embedded or legacy browser, that list is the boundary.

JointJS compared with a general-purpose canvas library

A canvas-based library such as one that draws to an HTML canvas element takes the opposite approach. It gives you a fast drawing surface and a scene graph, and you implement hit testing, connection semantics, serialization and layout yourself. For a large number of simple shapes, that can be the better trade: SVG creates a DOM node per element, and very large graphs put pressure on the browser's layout and paint work.

JointJS chooses SVG and accepts that cost in exchange for things that are hard to retrofit. Elements are DOM nodes, so CSS applies, text is real text, and accessibility tooling has something to attach to. The graph model is separate from the rendering, so you can compute over the graph without touching the DOM. The library also ships automatic layouts and a directed-graph layout package in the same workspace, which a raw canvas library leaves entirely to you.

The practical dividing line is what your users do with the diagram. If they look at it, a canvas renderer is often sufficient. If they edit it, connect it, embed nodes inside nodes, and expect links to route around obstacles, the model and routing work that JointJS already contains is the reason to pick it.

Maintenance, upgrades and licence implications

Upgrades are managed through changesets, which is visible from the .changeset directory in the repository root and the @changesets/cli dependency in package.json. That tooling produces per-release changelogs, so you can read what changed between versions of @joint/core rather than diffing the source. The packages version independently: @joint/core, @joint/react and @joint/router-avoid each carry their own release number, so an upgrade plan has to track them separately.

Contributing has its own cost. The repository requires Node 22.14.0 specifically, and the README warns that this version avoids syntax errors during installation. Yarn must be 2.0.0 or higher because the workspace uses Yarn workspace ranges. A team building an application never touches these constraints, but a team forking the library inherits them.

On licensing, the repository is MPL-2.0 and the root package.json declares the same. MPL-2.0 is a file-level copyleft licence: modifications to covered files carry obligations when distributed, while larger works that combine the library with your own code are treated separately. JointJS+ is a commercial product with its own terms and a 30-day trial, so the two are not interchangeable. This is a description of what the repository states, not legal advice; if you plan to modify the library and distribute it, read the licence text and get your own counsel.

Editorial conclusion

Adopt JointJS if you are building a diagram editor inside a web application and you need a graph model with traversal, ports, link routing and automatic layouts rather than a drawing surface. Do not adopt it if you need the stencils, inspectors and toolbar plugins, since those live in the commercial JointJS+ package, or if your target is a browser outside the supported list. Before committing, verify that @joint/core on npm matches the version you intend to pin, and check whether your use case depends on a JointJS+ feature.

Frequently asked questions

Official sources

1. clientIO/joint on GitHub
2. License: MPL-2.0
3. Project website
4. README
5. Releases