How do I get started with Sigma.js in an existing project?

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.