sigmajs.org

Sigma.js is a JavaScript library for rendering and interacting with network graphs in the browser, aimed at visualizing graphs of thousands of nodes and edges. You can use it to display an existing graph dataset, add interaction such as search and neighborhood highlighting, build graph editing interfaces, and customize how nodes are rendered. It handles rendering and interactions, while the companion library graphology handles the graph data model and algorithms.

The four use cases Sigma.js describes

The library's own documentation groups what you can build into four scenarios, each with a runnable Storybook example.

Display

The most basic case: you have a graph dataset with colors, sizes, and positions for each node, and you want to visualize it on a web page. A typical example is a GEXF graph file exported from Gephi. Sigma.js renders it directly.

Explore

You add interaction so users can dig into the graph. Concretely, this means adding a search field and letting users see the neighborhood of a node when hovering it.

Interact

You are developing a web application where users create and manipulate graphs themselves. This requires letting users create nodes on click and drag and drop nodes.

Customize

You personalize how graphs are rendered — for example, displaying some nodes with pictures inside them and others differently.

How Sigma.js and graphology divide the work

Sigma.js does not work alone. The architecture is a deliberate split:

The documentation states this as: graphology handles graph data model & algorithms, sigma.js handles graph rendering & interactions, and together they form your web app.

This split answers a common question directly: no graph algorithms are implemented in Sigma.js itself. Graphology has many, from ForceAtlas2 layout to various metrics and even community detection. So if you need layout computation or metrics, that work happens in graphology before Sigma.js draws anything.

It also explains the CSV question. To get drawable data from a CSV, you process the data with graphology, then render it with sigma.js. The documentation points to a specific example for this.

When Sigma.js is the right choice, and when it isn't

Sigma.js renders graphs using WebGL. That is the core trade-off:

• Choose Sigma.js when you need to draw larger graphs faster than Canvas- or SVG-based solutions allow. The library is explicitly aimed at graphs of thousands of nodes and edges.
• Choose d3.js instead if you have small graphs (the documentation's own framing: like a few hundreds of nodes and edges) and/or you need very customized rendering. The docs state plainly that in that case d3.js is indeed the best fit.

Note the second half of that trade-off: WebGL makes custom rendering way harder to develop. So "I need something visually unusual" pushes toward d3.js, while "I need scale" pushes toward Sigma.js.

Getting it into an existing project

Two entry points, depending on your starting point:

If you want Sigma.js in an existing project:

npm install graphology sigma

The documentation directs you to the quickstart guide for the next steps.

If you are starting from nothing: the docs suggest trying a provided CodeSandbox.

If you are in React: yes, Sigma.js works in a React application. The documentation says the best way is certainly to use @react-sigma. The interactive example on the Sigma.js homepage is itself built with it, and the source code is available to inspect. The page also begins to address Angular usage, so Angular is covered as well.

What to check before committing

• Confirm your data can be expressed as a graphology graph — that is the required input path for rendering.
• If your rendering needs are highly custom, test the WebGL constraint early rather than after building the app around Sigma.js.
• If you need layout or metrics, plan for graphology in your dependency list, not just Sigma.js.

Install two packages and you can render your first graph: npm install graphology sigma. Sigma.js handles rendering and interaction in the browser, while graphology holds the graph data model and algorithms — you need both, even for a minimal setup. This guide assumes you already have a JavaScript project with a bundler (the docs point to npm, so a Node-based build is the expected baseline).

What you're actually installing

Sigma.js is a JavaScript library for rendering and interacting with network graphs in the browser, aimed at graphs of thousands of nodes and edges. It works in symbiosis with graphology:

A useful consequence: if you later ask "what graph algorithms does Sigma.js implement?", the answer is none — they live in graphology. Keep that split in mind as your app grows.

Step 1: Install

npm install graphology sigma

Expected result: both packages appear in your dependencies and resolve without peer-dependency errors.

Step 2: Build a graph and render it

The minimal flow is: create a graphology graph, add nodes (with positions, and optionally colors and sizes), then hand it to Sigma for rendering.

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

const graph = new Graph();
graph.addNode("a", { x: 0, y: 0, size: 10, color: "#e63946", label: "A" });
graph.addNode("b", { x: 1, y: 1, size: 10, color: "#457b9d", label: "B" });
graph.addEdge("a", "b");

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

Expected result: the graph draws inside the container element. Nodes need x/y positions — if your dataset lacks them, run a layout in graphology first.

Step 3: Pick your starting point

The docs offer two entry paths, and which one fits depends on what you already have:

• Existing project — use the npm install above, then follow the quickstart guide for configuration details.
• Starting from nothing — the docs recommend a CodeSandbox template, which gives you a working setup without wiring a build yourself.

Common tasks and where they lead

The library's own use cases map cleanly onto what you'll want next:

• Display — you have a dataset with colors, sizes and positions per node (for example a GEXF file exported from Gephi) and just want it on a page.
• Explore — add a search field and let users see a node's neighborhood on hover.
• Interact — let users create nodes on click and drag and drop them.
• Customize — render some nodes with pictures and others differently.

Each of these has a Storybook example linked from the site, so you can start from a working demo rather than a blank file.

If you're using React

Yes, Sigma.js works in React, and the recommended approach is @react-sigma. The demo on the Sigma.js homepage is built with it, and its source code is available if you want a reference implementation. There is also guidance for Angular, though the React path is the one the docs call out most directly.

When this setup is the wrong choice

Sigma.js renders with WebGL, which lets it draw larger graphs faster than Canvas- or SVG-based solutions. The trade-off is explicit in the docs: custom rendering becomes considerably harder to develop. So:

• Choose Sigma.js when your graphs are large (thousands of nodes and edges) and standard rendering is enough.
• Choose d3.js when your graphs are small (a few hundred nodes and edges) and/or you need highly customized rendering.

FAQ worth knowing before you start

Can I get drawable data from a CSV? Yes — process the data with graphology, then render with sigma.js. The docs point to a worked example.

Where do layouts and metrics come from? Graphology, not Sigma.js. ForceAtlas2, various metrics and community detection are all there, with an overview in the graphology documentation.

Use Sigma.js when your graph has thousands of nodes and edges and you need it to render and stay interactive in the browser. Use d3.js instead when your graph is small (roughly a few hundred nodes and edges) or when you need highly customized rendering. The deciding factors are graph size and how much control you need over how each element is drawn.

The core difference: WebGL vs Canvas/SVG

Sigma.js renders graphs with WebGL. That is the main reason it can draw larger graphs faster than Canvas- or SVG-based solutions. d3.js typically renders through Canvas or SVG, which gives you fine-grained control over every drawn element but scales worse as the node and edge count grows.

The trade-off is explicit in the library's own guidance: WebGL lets Sigma.js draw larger graphs faster, but it "makes custom rendering way harder to develop." So the same mechanism that wins on scale is the one that costs you flexibility.

Choose Sigma.js when scale is the priority

Pick Sigma.js if any of these describe your situation:

• You have a graph dataset with thousands of nodes and edges and need it to render in a web page.
• You want built-in interaction — for example, a search field, or showing a node's neighborhood on hover.
• You are building an app where users create and manipulate graphs (creating nodes on click, drag-and-drop).
• You want to personalize rendering at a normal level, such as displaying some nodes with pictures in them and others differently.

Sigma.js is designed to work in symbiosis with graphology: graphology handles the graph data model and algorithms, while Sigma.js handles rendering and interactions. If you need graph algorithms — from ForceAtlas2 layout to metrics or community detection — those live in graphology, not Sigma.js.

Choose d3.js when customization is the priority

The library's own FAQ is direct on this: if you have small graphs (like a few hundred nodes and edges) and/or you need very customized rendering, then d3.js is the best fit. Reach for d3.js when:

• Your graph is small enough that Canvas or SVG performance is not a concern.
• You need rendering control that goes beyond what Sigma.js makes easy.
• Your visualization is less about a large interactive network and more about bespoke drawing.

How to get started with Sigma.js

If you have decided Sigma.js fits, the setup depends on your starting point.

Adding it to an existing project:

npm install graphology sigma

Starting from nothing: the project points to a CodeSandbox as a starting point.

A common first task is displaying an existing dataset — for example, a GEXF graph file exported from Gephi, with colors, sizes, and positions for each node — on a web page. From there you can layer on interaction (search, hover neighborhoods) or customization (image nodes, differentiated styling).

Common questions that affect the choice

Can I get drawable data from a CSV? Yes — process the data with graphology, then render it with Sigma.js.

Does Sigma.js include graph algorithms? No. Sigma.js implements none; graphology provides them, from ForceAtlas2 layout to metrics and community detection.

Can I use Sigma.js in React? Yes, and the recommended approach is @react-sigma. The demo on the Sigma.js site is built with it, and its source is available for reference.

The short version: let graph size and rendering-customization needs decide. Large and interactive points to Sigma.js; small and highly custom points to d3.js.

Sigma.js and graphology are two separate JavaScript libraries designed to be used together: graphology handles the graph data model and algorithms, while Sigma.js handles rendering and interaction in the browser. You need both because Sigma.js does not store or compute graph data itself — it draws whatever graphology gives it. If you only install Sigma.js, you have a renderer with nothing to render; if you only use graphology, you have graph data and algorithms but no WebGL visualization.

The division of labor

The Sigma.js site states the relationship directly: graphology is "a multipurpose graph manipulation library" and Sigma.js "works in symbiosis" with it.

The site summarizes this as: graphology handles graph data model & algorithms, Sigma.js handles graph rendering & interactions.

A practical consequence: Sigma.js implements no graph algorithms of its own. As the FAQ puts it, "None in sigma.js, but graphology has a lot, from ForceAtlas2 layout to various metrics or even community detection."

Why the split matters in practice

Because the two libraries are decoupled, you can prepare and transform data with graphology without touching rendering code, then hand the finished graph object to Sigma.js. This is also why the answer to "how do I get drawable data from a CSV?" is a two-step process: process the data with graphology, then render it with Sigma.js.

The same pattern applies to other sources. If you export a GEXF file from Gephi, graphology holds the nodes, edges, colors, sizes, and positions, and Sigma.js draws them on a web page.

Getting both into a project

The quickstart on the site gives the install command for an existing project:

npm install graphology sigma

From there, the typical flow is:

1. Build the graph in graphology — create a Graph instance, add nodes and edges, and attach attributes such as color, size, and position.
2. Run any layout or metrics in graphology — for example ForceAtlas2, if your nodes do not already have coordinates.
3. Pass the graph to Sigma.js — Sigma.js reads the graphology instance and renders it, then handles interactions on top.

If you are starting from nothing, the site points to a CodeSandbox rather than a from-scratch setup, which is the faster way to see the two libraries wired together.

Choosing this stack over alternatives

The main reason to accept the two-library split is scale. Sigma.js renders using WebGL, which "allows drawing larger graphs faster than with Canvas or SVG based solutions." The trade-off, stated on the site, is that this "makes custom rendering way harder to develop."

So the choice depends on your graph size and how much you need to customize rendering:

• Large graphs (thousands of nodes and edges), standard rendering needs — Sigma.js plus graphology is the intended fit.
• Small graphs (a few hundred nodes and edges) or heavily customized rendering — the site says d3.js "is indeed a best fit for you."

Using it inside a framework

For React applications, the site recommends @react-sigma as "certainly" the best approach; the demo on the Sigma.js homepage is built with it, and its source is available to inspect. The page also begins to address Angular usage, so framework-specific wrappers exist beyond plain JavaScript.

What to check before committing

• Confirm your data can be expressed as a graphology graph — CSV, GEXF, and similar sources all go through graphology first.
• Decide whether you need a layout algorithm; if your nodes already have positions, you can skip that step.
• Estimate your node and edge counts. If you are in the low hundreds and need unusual rendering, evaluate d3.js before adopting this stack.

Sigma.js is a JavaScript library for rendering and interacting with network graphs in the browser. It is built for graphs with thousands of nodes and edges, and it pairs with a separate library called graphology: graphology handles the graph data model and algorithms, while Sigma.js handles rendering and interaction. If you have a graph dataset and want it displayed on a web page, Sigma.js is the rendering layer you would reach for.

How the two libraries split the work

The architecture is deliberately divided:

The site describes this as a symbiosis: graphology plus Sigma.js equals your web app. A practical consequence is that Sigma.js itself implements no graph algorithms. If you need layout computation, centrality metrics, or community detection, those come from graphology, and you render the result with Sigma.js.

Why WebGL matters here

Sigma.js renders graphs using WebGL. That is the main reason it can draw larger graphs faster than Canvas- or SVG-based solutions. The trade-off is stated plainly on the site: custom rendering is harder to develop with Sigma.js.

That gives a fairly clear dividing line:

• Choose Sigma.js when your graph is large (thousands of nodes and edges) and you want speed.
• Choose d3.js when your graph is small (a few hundred nodes and edges) and/or you need highly customized rendering.

Getting it into a project

For an existing project, the quickstart path is:

npm install graphology sigma

From there you follow the quickstart guide. If you are starting from nothing, the site points to a CodeSandbox to try it immediately.

For React applications, the recommended approach is the @react-sigma package. The interactive example on the Sigma.js homepage is built with it, and its source code is available to inspect.

What you can build with it

The site groups use cases into three levels:

Display

The most basic case: you already have a graph dataset with colors, sizes, and positions for each node — for example, a GEXF file exported from Gephi — and you want to visualize it on a web page.

Explore

You add interaction so users can dig into the graph: a search field, or seeing a node's neighborhood on hover.

Interact and customize

You build an application where users create and manipulate graphs — creating nodes on click, dragging and dropping nodes — or you personalize rendering, such as showing some nodes with pictures inside them and others differently.

Common questions

Can I use CSV data? Yes, but not directly. You process the data with graphology first, then render it with Sigma.js. The site links to an example of this.

Does Sigma.js include graph algorithms? No. graphology provides them, from ForceAtlas2 layout to metrics and community detection.

Can I use it in React? Yes, via @react-sigma. The site also notes Angular support exists, though the excerpt is cut off at that point.

The short version: if your graph is large and you want it fast in the browser, Sigma.js plus graphology is the intended combination. If your graph is small or your rendering needs are unusual, d3.js is likely the better fit.