Skip to content
Get packs

Guide · Open source

How to use Cytoscape.js: graphs, rendering and Node.js

Updated · written with AI from the project's own documentation and checked against our catalogue data

Cytoscape.js is a JavaScript library for working with graphs, which are collections of nodes connected by edges, such as biological pathways or social networks. It has a graph model for analysis and an optional renderer that displays interactive graphs in a web page. This guide shows you what it is for, how to install it with npm and create your first graph, and where to go next.

Cytoscape.jscytoscape/cytoscape.js · ★ 11.3k · MIT

Quick start

  1. 1Check prerequisites. Make sure Node.js and npm are installed on your machine.
  2. 2Install the library. Add Cytoscape.js to your project using npm, or build it from source with npm install followed by npm run build.
  3. 3Prepare your elements. Decide which nodes and edges your data contains, following the element format in the official documentation.
  4. 4Create a container. Add an empty div to your web page that will hold the graph.
  5. 5Call cytoscape. Pass your elements and the container to cytoscape({ elements, container }) to create the graph instance.
  6. 6Explore the docs. Use js.cytoscape.org to learn the features, styling and interaction options.

What Cytoscape.js is for

Cytoscape.js is a fully featured graph theory library. It is meant for situations where you need to model or visualise relational data, such as biological data or social networks.

It contains a graph theory model and an optional renderer. The model handles the graph itself, and the renderer displays interactive graphs. It can run in a browser user interface or in server-side Node.js code.

  • Developers adding interactive network diagrams to a web app
  • Scientists modelling and visualising relational data such as biological networks
  • Teams wanting graph analysis in Node.js without a separate tool
  • Students learning graph theory who want to experiment in JavaScript

Install Cytoscape.js with npm

The library is distributed as a package and the prerequisites are Node.js and npm. Install both first, then add the package to your project.

If you want to build the library from source instead, the README says to run npm install to set up build dependencies, then npm run build to build all library targets.

  • Prerequisites: Node.js and npm
  • Building from source: run npm install, then npm run build
npm install npm run build

Create your first graph

The README shows that you can start with one line. Pass your elements and a container element (a div on your page) to the cytoscape function. The result, stored in cy here, is the graph instance you work with.

Elements are the nodes and edges of your graph. The source does not detail the element format, so check the official documentation at js.cytoscape.org for the exact shape of your data.

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

Use it in a browser page or in Node.js

In a browser, the graph is drawn inside the container you give it, and the renderer makes it interactive. The README notes that the renderer is optional, so you can also use the graph model alone for analysis.

In Node.js, you can use the library for server-side analysis of graph data. The README describes this as one of its two main uses, alongside rich user interfaces.

  • Browser: the renderer draws an interactive graph in a web page
  • Node.js: use the graph model for server-side analysis

Build options and development targets

The build script has several targets. The README lists build for all targets, a minified unminified build for simple HTML pages, and watch modes for debugging.

Use npm run build:min for a simple HTML page, since the README describes it as good for novices. Use watch when you are developing the library itself, which serves a debug page on localhost:8080 or the next free port.

  • npm run build: all builds of the library (umd, min, cjs, esm)
  • npm run build:min: unminified build with bundled dependencies, good for simple HTML pages
  • npm run test: run all testing and linting
  • npm run docs: build the docs into documentation
npm run build:min npm run watch

Find examples and documentation

The project website at js.cytoscape.org holds the documentation, downloads and demos. A live Tokyo railway stations demo, with its source code, is linked from the README and is a good example of a real graph.

The README also points to a blog for news and tutorials.

  • Documentation and downloads: js.cytoscape.org
  • Live demo: Tokyo railway stations graph
  • Blog: blog.js.cytoscape.org

What people use it for

  • Drawing an interactive network diagram inside a web app
  • Modelling biological pathways or other relational scientific data
  • Running graph analysis on the server in a Node.js app
  • Learning graph theory by experimenting with small graphs in JavaScript

Frequently asked questions

Is Cytoscape.js free to use?

Yes. The repository is released under the MIT licence, as shown in the README. You can read the full LICENSE file in the GitHub repository.

What do I need to install Cytoscape.js?

The README lists Node.js and npm as prerequisites. Install them, then add the library to your project.

Can I use Cytoscape.js in Node.js?

Yes. The README says it can be used for server-side analysis in a Node.js app, as well as in browser user interfaces.

Is Cytoscape.js a desktop application?

No. The README describes it as a library, so it is code you integrate into your own project rather than a finished desktop program.

Can Cytoscape.js store my graph in a database?

No. The README covers an in-memory graph library, so it is not a graph database for storage.

How does Cytoscape.js compare to D3.js, Sigma.js, vis-network or Graphology?

The source lists these as comparable projects but does not compare them. Look at each project's documentation to decide which fits your needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Cytoscape.js suits developers adding interactive network diagrams to a web app, and scientists or students who need graph analysis in JavaScript or Node.js. If you only need a static chart, want a finished desktop application, or need a graph database for storage, pick a different tool.

Install options & downloads