Guide · Open source

How to use sigma.js: install and draw a graph in the browser

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

Sigma.js is an open-source JavaScript library for displaying network graphs, meaning nodes connected by edges, in a web page. It uses WebGL, a browser technology for fast graphics, and is aimed at graphs with thousands of nodes and edges. This guide shows you how to install it, create a small graph with graphology and render it in a container on your page.

Sigma.jsjacomyal/sigma.js · ★ 12.2k · MIT Install options & downloads

Quick start

1Check prerequisites. Make sure Node.js and npm are installed on your machine. Sigma is installed through npm.
2Install sigma and graphology. Run npm install sigma graphology in your project folder.
3Import the libraries. In your JavaScript or TypeScript file, import Graph from graphology and Sigma from sigma.
4Build a graph. Create a graph and add nodes with id, label, x, y, size and color, then add edges between node ids.
5Add a container. Create an element in your page with an id, such as container, and give it a height and width in CSS.
6Create the Sigma instance. Call new Sigma with your graph and the container element to render the graph.
7Add companion packages if needed. Install packages such as @sigma/node-image or @sigma/layer-leaflet only when your project requires them.

What sigma.js is and who it is for

Sigma.js is built on top of graphology, a companion library for storing graph data. You describe your nodes and edges with graphology, then pass that graph to a Sigma instance, which draws it in the page.

It suits web developers who need large network graphs in a browser, data analysts building interactive graph visualizations on a website, and teams already using graphology. It is a library, not a finished tool, so you need to write code to use it.

Good fit: displaying large network graphs in a browser
Good fit: teams already using graphology
Not a fit: simple charts or bar graphs
Not a fit: people who want a finished tool with no coding

Install sigma and graphology

You need Node.js and npm. Sigma is installed with the package manager, together with graphology, from inside your project folder.

npm install sigma graphology

Create a graph and add nodes and edges

Import both libraries in your JavaScript or TypeScript file. Then create a graph and add nodes with an id and attributes such as label, x and y position, size and color. Edges connect two node ids and can also have attributes like size and color.

import Graph from "graphology";
import Sigma from "sigma";

const graph = new Graph();
graph.addNode("1", { label: "Node 1", x: 0, y: 0, size: 10, color: "blue" });
graph.addNode("2", { label: "Node 2", x: 1, y: 1, size: 20, color: "red" });
graph.addEdge("1", "2", { size: 5, color: "purple" });

Render the graph in a container element

Create a new Sigma instance with your graph and a target container. The container is a page element, here one with the id container. Give that element a height and width in your CSS, otherwise there is nothing visible to draw into.

Pass the graph as the first argument
Pass the DOM element as the second argument
Keep a reference to the instance if you want to work with it later

const sigmaInstance = new Sigma(graph, document.getElementById("container"));

Add optional companion packages when you need them

Sigma ships several companion packages. Install only the ones you need. They cover node rendering (images, borders, pie charts), background maps via Leaflet or MapLibre, custom WebGL layers, image export of a sigma instance, and utility functions.

@sigma/node-image: renders nodes as images
@sigma/node-border: renders nodes as concentric discs
@sigma/node-piechart: renders nodes as piecharts
@sigma/layer-leaflet and @sigma/layer-maplibre: put a map in the background
@sigma/layer-webgl: helpers for custom WebGL layers
@sigma/export-image: captures snapshots as images
@sigma/utils: utility functions

Find more detail in the documentation

The official documentation at sigmajs.org/docs has extensive guides, interactive examples and API references. The website also includes live examples, and the source code is on GitHub. To run the website locally, clone the repository, run npm install and then npm run start.

git clone https://github.com/jacomyal/sigma.js.git
cd sigma.js
npm install
npm run start

What people use it for

Showing a large network of relationships on a website, with nodes and edges drawn in WebGL
Building an interactive graph view for data analysis inside a web app already using graphology
Displaying nodes as images or pie charts with the optional node packages
Placing a graph over a Leaflet or MapLibre map with the layer packages
Exporting a snapshot of a graph as an image with @sigma/export-image

Frequently asked questions

Is sigma.js free to use?

Sigma.js is released under the MIT licence, and the source is public on GitHub. Check the licence file in the repository for the full terms before using it in a commercial project.

What do I need to install sigma.js?

The README lists Node.js and npm as prerequisites. You install sigma and graphology together with npm install sigma graphology.

Does sigma.js need graphology?

Yes. Sigma is built on top of graphology, and you create your graph data with graphology before passing it to Sigma.

Can sigma.js handle thousands of nodes?

Sigma is aimed at visualizing graphs of thousands of nodes and edges, using WebGL for fast rendering. The README does not publish benchmarks, so test with your own data size.

Is sigma.js stable enough for production?

The README notes that v4 development included LLM-drafted code and that the API is evolving. If your project needs a long track record of stable APIs, weigh this before adopting it and pin your versions.

What are alternatives to sigma.js?

Comparable projects mentioned include Cytoscape.js, vis.js, G6 and Graphology. Sigma is specialized for graphs, so pick a library based on your data size, features and how much you want to build yourself.

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

Sigma.js is a good choice for web developers who need to draw large network graphs in a browser and are comfortable writing code, especially if they already use graphology. If you only need a simple chart, or you want a finished tool without coding, pick a different option. Because the API is still evolving, check the documentation and pin versions before relying on it long term.

Install options & downloads