# Graphology: one Graph object that covers directed, mixed and multi-edge graphs

> Graphology is a JavaScript and TypeScript graph data structure whose selling point is a single unified interface across directed, undirected and mixed graphs, with self-loops and parallel edges as configuration rather than as separate types. Around the core sits a separate standard library of algorithms, layouts and generators, and an event system aimed at interactive renderers.

**graphology/graphology** — A robust & multipurpose Graph object for JavaScript & TypeScript.

- Repository: https://github.com/graphology/graphology
- Website: https://graphology.github.io
- Stars: 1,763 · Forks: 117
- Language: JavaScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/graphology-graphology

## One interface instead of a family of graph classes

Graphology is described as a robust and multipurpose Graph object for JavaScript and TypeScript, aiming at supporting various kinds of graphs with the same unified interface.

That aim is the design. A graph library can force you to pick a class early, and a directed graph chosen on day one becomes a liability the day you need one reciprocal edge. Graphology instead makes those properties of an instance: a graph can be directed, undirected or mixed, can allow self-loops or not, and can be simple or support parallel edges. The API is the same either way.

The consequence is worth stating plainly, because it is what an adopter actually buys. You can start with an undirected graph of collaborators, discover that the data has an orientation, and add directed edges to the same object rather than migrating to a different library or writing two code paths. Mixed graphs are the case where this matters most, since real relationship data is rarely uniformly directed.

Around the object sits a comprehensive standard library of graph theory algorithms and common utilities, including graph generators, layouts and traversals, published under its own name. It is a separate artifact from the core object, and that separation is described in detail further down, because it has practical consequences for how you install and version things.

## The event system is what makes it a renderer backend

Graphology graphs emit a wide variety of events, and the README names interactive browser renderers as the reason, giving sigma.js as the concrete case: sigma.js uses graphology as its data backend.

That framing matters. A renderer has three options. It reads the graph once and redraws entirely when the application says so. It polls the graph. Or it subscribes to changes and updates only what moved. Events are the third option, and they are the difference between a graph library that a visualisation can sit on top of and one it has to mirror.

For a large graph the difference is not cosmetic. A redraw of a few thousand nodes on every interaction is a different experience from patching one edge. This is the part of Graphology that has nothing to do with algorithms and everything to do with why the project describes itself as multipurpose.

The practical consequence for an adopter is that the event vocabulary is part of the contract, not an implementation detail. If you are writing a renderer, you are writing against those events, and the documentation site is the reference for the list.

## Installing, the legacy bundle, and the TypeScript caveat

The npm install is the normal one:

```bash
npm install graphology
```

There is a second path for environments where you can only rely on your own script tags, which is not a hypothetical case for a browser project with a strict content security policy or an internal library you cannot bundle:

```html
<script src="graphology.min.js"></script>
<script>
  const graph = new graphology.Graph();

  const {UndirectedGraph, DirectedGraph} = graphology;
</script>

<script src="graphology-library.min.js"></script>
<script>
  const density = graphologyLibrary.metrics.graph.density(graph);
</script>
```

Two globals come out of that: graphology for the Graph object and graphologyLibrary for the standard library, and the second example shows that a metric such as density comes from the library bundle rather than the core.

And here is the warning the README attaches to exactly that path: the standard library bundle often lags behind and is not always completely up to date. If you are on script tags you are accepting a version skew between the object and the algorithms applied to it, which is a real risk when a standard library release has added a method the older bundle does not carry.

For TypeScript there is a footnote worth acting on. Type declarations ship as peer dependencies so the package works out of the box, but on an older npm the peer dependency resolution may not happen for you, and the README suggests installing graphology-types directly:

```bash
npm install graphology-types
```

It also says pinning the graphology-types version in your package.json can avoid resolution issues, which is a hint that the type package and the core package must agree and that npm will not always make them agree for you.

## Versioning: the object, the library and the bundle move separately

The release history explains the separation described above.

The tagged releases are 0.25.3 from 2023-07-27, 0.25.4 from 2023-08-01, and 0.26.0 from 2025-02-08. So the core object had two patch releases in a burst in mid 2023, then nothing until a minor release in early 2025. The repository's last push was on 2026-09-02 and it is not archived, so source changes are still landing between tags.

Two consequences follow from a 0.x line with irregular releases. First, a minor release is where breaking changes land, so 0.25.x to 0.26.0 is the upgrade to read the changelog for. Second, an irregular cadence means the standard library packages, the layout packages and the browser bundles are released on their own schedules, which is precisely the skew the README warns about for the legacy bundle.

The repository is a lerna monorepo, and the build script shows the shape of it: it cleans everything, then builds graphology, then runs a template step for graphology-layout-forceatlas2 and graphology-layout-noverlap, then builds graphology-library. The forceatlas2 layout and the noverlap layout have a build template step of their own, which is the clearest indication in the repository that layouts are separate packages with generated artifacts rather than files inside the standard library bundle.

Documentation is a Jekyll site built from docs/, with bundle and jekyll commands in the npm scripts, and a script that regenerates the standard library documentation from source.

## Limitations, and where the 0.x line bites

The first limitation is that graphology is a data structure, not an algorithm library, and the algorithm library is a different package. If you install graphology expecting layout, traversal and centrality to come with it, you will find an empty standard library until you add it. The reverse is also true: pinning the core object version does not pin the algorithms, so a reproducible build needs both pinned.

The second is the 0.x versioning. A project on the 0.x line signals that its interface can still change, and 0.25.4 to 0.26.0 is exactly the kind of step that can rename or reorder an API. The changelog is the mitigation and it exists.

The third is the legacy bundle skew, already described. It is the sharpest operational edge in this README: a script tag user can end up with a graphology and a graphologyLibrary from different points in time, and the failure will look like a method that does not exist rather than a version error.

The fourth is that a multipurpose interface has costs at the edges. If your graph is definitely simple, directed and loop free, a typed structure that only offers exactly that is faster to use and faster to reason about, and graphology's flexibility is a feature you are paying for in verbosity. The unified interface also means some operations have semantics you have to check rather than infer, which is the usual bargain with general purpose containers.

The fifth is ecosystem scale. The README cites sigma.js as a user of the data backend. A library with a published DOI, a Zenodo record and a documentation site is a serious project, but JavaScript graph work is also well served by larger ecosystems, and graphology's reach is concentrated in the visualisation community.

## How the alternatives differ

The common alternatives are a graph library scoped to one graph type, and an adjacency map you write yourself.

For typed scope, the difference in approach is compile time versus runtime flexibility. A library that only models directed graphs gives you method signatures and type definitions that rule out misuse, and costs you when the data turns out to be mixed. Graphology moves that decision to runtime on an instance, so a mixed graph is a first class case rather than a workaround.

Against a hand written adjacency map, the comparison is clearer. Writing your own means you own the traversal code, the edge case handling and the change notification. You also own the bugs, and the specific bugs of graphs, which are the ones about self loops, duplicate edges and events firing for removals.

The second alternative is a graph library bundled with a rendering library, where the graph type is coupled to the renderer. That is a better fit if you are certain you will only ever render with one library, and worse if the same graph model later needs to live on a server where the renderer does not.

So the deciding question is whether your graph will change shape. If it might, the unified interface is the reason to choose this one; if it certainly will not, a narrower type is the better trade.

## Conclusion

Adopt Graphology if your JavaScript or TypeScript work holds a graph that changes shape as the problem evolves, because the same Graph class covers directed, undirected and mixed graphs and the event system lets a renderer react to a single data structure rather than polling it. Do not reach for it as an all in one package: the Graph object and the standard library of algorithms and layouts are separately versioned artifacts, and the standalone bundle is explicitly described as often lagging and not always up to date. Verify first which graphology-types version your npm resolves, since the README suggests installing it separately or pinning it by hand if peer dependency resolution on an older npm leaves you with a mismatch.

## FAQ

### How do I install graphology in a JavaScript project?

Run npm install graphology for the npm path. If you can only use script tags, standalone builds of graphology and its standard library are published in the repository releases, exposing globals named graphology and graphologyLibrary.

### Why should I avoid the graphology legacy bundle?

The README warns that the standard library bundle often lags behind and is not always completely up to date, so a script tag user can end up with a core object and a standard library from different points in time. Pinning both versions through npm avoids that.

### What graph types does a graphology Graph support?

The same Graph object can be directed, undirected or mixed, can allow self-loops or not, and can be simple or support parallel edges. Those are instance properties rather than separate classes, which is the unified interface the project describes.

### Do I need to install anything extra to use graphology with TypeScript?

Type declarations ship as peer dependencies so it works out of the box, but on an older npm the resolution may not happen. The README suggests running npm install graphology-types and, if needed, pinning the graphology-types version in your package.json.

### Which rendering library uses graphology as its data backend?

sigma.js, according to the README, which is the reason graphology emits a wide variety of events. Those events are described as making it suitable for building interactive renderers in the browser.

## Sources

- [graphology/graphology on GitHub](https://github.com/graphology/graphology)
- [License: MIT](https://github.com/graphology/graphology/blob/master/LICENSE)
- [Project website](https://graphology.github.io)
- [README](https://github.com/graphology/graphology/blob/master/README.md)
- [Releases](https://github.com/graphology/graphology/releases)

---

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