# Cytoscape.js: a graph theory library for visualisation and analysis

> Cytoscape.js is an MIT-licensed JavaScript library that pairs a graph model with an optional renderer, built for programmers and scientists who need relational data both computed and drawn. It installs from npm or a CDN, and its monthly feature releases plus weekly patches are the main reason to check the changelog before upgrading.

**cytoscape/cytoscape.js** — Graph theory (network) library for visualisation and analysis

- Repository: https://github.com/cytoscape/cytoscape.js
- Website: https://js.cytoscape.org
- Stars: 11,221 · Forks: 1,676
- Language: JavaScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/cytoscape-cytoscape-js

## What Cytoscape.js actually solves, and for whom

Relational data is awkward in most JavaScript drawing libraries. You have a list of things and a list of connections between them, and the drawing library wants shapes and coordinates. Cytoscape.js closes that gap by shipping a graph theory model alongside an optional renderer, so the same object you query for paths is the object you draw. The README frames the audience directly: it asks whether you need to model or visualise relational data such as biological data or social networks, and says the library was designed for programmers and scientists using graph theory in their apps, whether for server-side analysis in a Node.js app or for a rich user interface.

That dual framing matters when you are choosing a tool. If you only need a picture, you have cheaper options. If you need to compute on the structure (reachability, shortest paths, neighbourhoods) and then show the result, the fact that the model and the view are the same object saves you from maintaining a translation layer. The project originated at the University of Toronto and was published in Oxford Bioinformatics in 2016, with a 2023 update article, which tells you the intended readership is closer to a lab than to a marketing dashboard.

## How the model and the optional renderer fit together

The README's one-line example is the clearest statement of the architecture: the library is initialised with an elements list and a container, and you get back a cy instance that serves as both the graph and its controller. Elements are the input; the container is a DOM element. Omit the container and you still have a graph you can run analysis on, which is how the server-side Node.js use case works. Supply it and the renderer takes over drawing.

The repository layout reflects that split. The source lives in src/, the built bundles in dist/, and there is a separate index.d.ts at the top level for TypeScript consumers. The package.json exports map is explicit about which artefact you get: an ESM build at dist/cytoscape.esm.mjs for import, a CommonJS build at dist/cytoscape.cjs.js for require, a UMD build at dist/cytoscape.umd.js, and a minified UMD at dist/cytoscape.min.js. The unpkg and jsdelivr fields both point at the minified UMD file, which is the one a plain script tag should pull.

Extensions are a separate concern from the core. The README badge counts 70 extensions, and the documentation site lists them. The search data around this project is full of layout questions, and that is the reason: layout algorithms beyond the built-in ones arrive as extensions rather than as part of the core package.

## Installing Cytoscape.js and drawing a first graph

The README points to the project website for documentation and downloads, and the package is published on npm. Install it with npm and import the ESM build; the exports map resolves that automatically.

```bash
npm install cytoscape
```

In a module, import the default export and pass an elements array plus a container element. The README gives the shape of this call, with myElements and myDiv as the two arguments.

```js
import cytoscape from 'cytoscape';

const cy = cytoscape({
  elements: myElements,
  container: myDiv
});
```

After this runs, cy is your handle on the graph. If you would rather not bundle anything, the package.json maps the unpkg and jsdelivr fields to dist/cytoscape.min.js, so a script tag against either CDN serves the minified UMD build and exposes cytoscape as a global.

To run the library from source instead, the build section of the README says to install node and npm, run npm install, then use npm run with the available targets. The debug target is the useful one for a first look: npm run watch builds with a sourcemap and no babel, serves on http://localhost:8080 or the first available port after that, and reloads debug/index.html. The README notes npm run watch:babel is the variant to use when testing performance or out-of-date browsers.

```bash
npm install
npm run watch
```

Running the test suite is a single npm run test for all testing and linting, or npm run test:js to run the mocha tests against the public API directly on the source files. The README shows that a single test case can be selected by passing a name through: npm run test:js -- -g "my test name".

## Where Cytoscape.js is the wrong choice

The library is a graph library, and the README does not pretend otherwise. If your data is a time series, a set of categories, or a table, you are paying for a graph model you will not use. A general charting library will get you there with less conceptual overhead.

The harder boundary is interaction design. Cytoscape.js gives you a graph you can style, lay out and query, but it is not a diagram editor. Nothing in the README describes node creation by dragging, edge routing by hand, or a persistence format for hand-edited diagrams. If your users need to draw and rearrange a flowchart, you are building that layer yourself on top of the model, and the renderer's job is display, not authoring.

The third boundary is scale, and here the documentation is thin. The README does not state a node or edge ceiling, and it does not describe what happens to layout time or frame rate as a graph grows. That silence is not a defect in the library, but it does mean the ceiling is something you have to find on your own with your own data. There is a benchmark/ directory in the repository, which suggests the maintainers measure performance, but the README does not publish numbers from it. Treat any figure you see elsewhere as unverified.

One more constraint worth naming: the package.json declares engines.node as >=0.10, and the README says the library can be built on node>=6 while the bundle can be tested on node>=0.10. Those are permissive floors, not recommendations. Nothing in the README says the current toolchain is tested on those versions.

## Cytoscape.js compared with D3, React Flow, Sigma.js and vis.js

The alternatives people search for alongside this project differ from it in one consistent way: how much of the graph abstraction they hand you.

D3 is a general data-driven document manipulation library. You bind data to DOM or SVG elements and control the rendering yourself. A force layout in D3 is a simulation you wire up; in Cytoscape.js the graph model, the layout and the renderer are already connected. The trade-off is control against setup. D3 lets you draw anything, including things that are not graphs, but you write more code to get a network on screen.

React Flow is a React component for node-based interfaces, the kind used for editors and flow builders. Its centre of gravity is the interactive canvas rather than graph algorithms. If your requirement is that users place and connect nodes, that framing is a better fit than Cytoscape.js, which the README positions around modelling and visualising relational data rather than authoring it.

Sigma.js and vis.js sit closer to Cytoscape.js. Both render networks in the browser. The difference the README supports is scope: Cytoscape.js describes itself as a fully featured graph theory library containing a model and an optional renderer, and it carries a citation trail in Oxford Bioinformatics. If you want analysis primitives in the same object as the view, that combination is the argument for this library over a renderer-only toolkit. If you only need pixels on a canvas, a renderer-only toolkit is smaller.

Layout is where the comparisons get practical. Searches for cytoscape.js with dagre are common because dagre is a layered layout that arrives as an extension rather than in the core. Budget for that: the core library plus at least one layout extension is the realistic dependency set for a directed acyclic graph.

## Release cadence, upgrade cost and the MIT licence

The README states the cadence plainly: feature releases are made monthly, while patch releases are made weekly, and it says this exists to allow rapid releases of first- and third-party contributions. The recent release list matches that description, with v3.34.1, v3.34.2 and v3.34.3 arriving in successive weeks. The last push to the repository was on 2026-09-16, and the default branch is unstable, which is where development lands before it is released.

A weekly patch cadence is good for bug turnaround and bad for anyone who pins a version and stops reading. The upgrade cost is not in the API surface, which the README presents as stable enough to document in one line, but in the volume of releases you have to triage. If you pin, pin deliberately and read the release notes for the versions you skip.

Building from source has its own cost. The build targets are numerous (build, build:min, build:umd, build:esm, clean, docs, release, watch, watch:babel, watch:umd, dist), each aimed at a different consumer. Most applications should never run them; they should install the published package and let the exports map pick the right bundle. The build scripts matter if you are contributing or patching.

The licence is MIT, stated in both the README badge and the package.json license field. MIT is permissive: it allows commercial and closed-source use. This is not legal advice, and if your organisation has a policy on attribution or on bundled third-party notices, check how you distribute the built bundle, because the minified UMD file is the one most likely to end up vendored into a page without a package manager tracking it.

## Conclusion

Adopt Cytoscape.js when your problem is genuinely a graph: nodes, edges and the algorithms over them, with an interactive view on top. Skip it when you need a general charting layer or a diagram editor, since neither is what the library models. Before committing, check the package exports in package.json against your bundler, confirm the renderer behaves in your target browsers, and read the changelog for the version you pin, because feature releases are monthly and patch releases weekly.

## FAQ

### Is Cytoscape.js free?

Yes. The README and the package.json both state the licence as MIT, which permits commercial and closed-source use. The library is published on npm and also served from unpkg and jsdelivr.

### Is Cytoscape.js open source?

Yes. The source is in the cytoscape/cytoscape.js repository, the licence is MIT, and the README links to CONTRIBUTING.md for the mechanics of submitting a pull request.

### What is Cytoscape.js used for?

It is a graph theory library for modelling and visualising relational data, such as biological data or social networks. The README describes it as containing a graph theory model and an optional renderer, usable for server-side analysis in Node.js or for a user interface.

### How do I use Cytoscape.js in a project?

Install it with npm install cytoscape, then call cytoscape with an elements array and a container element to get a cy instance. The README's example is cytoscape({ elements: myElements, container: myDiv }).

### What is Cytoscape.js?

It is a JavaScript graph theory library for visualisation and analysis, created at the University of Toronto and published in Oxford Bioinformatics. The README describes it as containing a graph theory model and an optional renderer.

### How does Cytoscape.js compare with D3?

D3 is a general data-driven document manipulation library where you control the rendering, while Cytoscape.js ships a graph model and an optional renderer together. The README positions Cytoscape.js as a fully featured graph theory library rather than a general drawing toolkit.

## Sources

- [cytoscape/cytoscape.js on GitHub](https://github.com/cytoscape/cytoscape.js)
- [License: MIT](https://github.com/cytoscape/cytoscape.js/blob/unstable/LICENSE)
- [Project website](https://js.cytoscape.org)
- [README](https://github.com/cytoscape/cytoscape.js/blob/unstable/README.md)
- [Releases](https://github.com/cytoscape/cytoscape.js/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cytoscape-cytoscape-js