GraphJS

GraphJS is a framework for easily representing and displaying graphs in JavaScript.

Objective

Very easy to use.

import { Graph, ForceDirected } from "graphjs";

// Load a graph from JSON ({ nodes, links } or { nodes, edges })
const graph = new Graph();
graph.loadJSON({
  nodes: [{ id: "a" }, { id: "b" }, { id: "c" }],
  edges: [{ source: "a", target: "b" }, { source: "b", target: "c" }],
});

// Lay it out with the force-directed simulation
const layout = new ForceDirected(graph, { center: { x: 400, y: 300 } });
layout.on("tick", () => { /* nodes have updated x / y — draw them */ });
layout.on("end",  () => { /* simulation settled */ });
layout.start();

Layouts

Examples

Interactive demos (click a thumbnail above, or open them directly):

| Demo | Try it | Play with | |------|--------|-----------| | GraphChart (SVG renderer) | graph-chart.html | drag · zoom · hover · toggle node/link renderers — the chart draws the SVG | | Canvas backend (scale) | canvas-scale.html | ~1,280 nodes on the Canvas backend (auto-selected) — same drag/zoom/hover | | Org chart | org-chart.html | click a card to collapse · drag to pan · scroll to zoom | | Force-directed | force-directed.html | drag any node and watch the simulation settle | | Radial | radial.html | click any node to re-center the rings around it | | Tree (Walker's) | tree-layout.html | hover to trace lineage · click a node to collapse |

Each demo is a single self-contained HTML page that imports the library bundle (examples/graphjs.esm.js) — no build step, no server; open the file and it runs.

Headless SVG scripts — the thumbnails above are produced by the scripts in examples/. Each builds a graph, runs a layout, and renders an SVG (see examples/render.js for the tiny headless renderer):

| Script | Layout | |--------|--------| | examples/org-chart.js | TreeLayout (Walker's algorithm) | | examples/force-directed.js | ForceDirected | | examples/radial.js | RadialLayout |

Regenerate them with:

bun run examples        # writes examples/img/*.svg
bun run examples:lib    # rebuilds examples/graphjs.esm.js (the demo bundle)

Development

GraphJS is bundled with Bun (no Rollup/Webpack). The source is native ES modules.

bun install        # install dev tooling (nothing external is required to build)
bun run build      # produce dist/esm, dist/cjs and dist/umd bundles
bun test           # run the test suite
bun run dev        # rebuild the ESM bundle on change (watch mode)

Build outputs

| Field | File | Format | |-----------|-----------------------------|--------| | module | dist/esm/index.js | ESM (import) | | main | dist/cjs/index.cjs | CommonJS (require) | | browser | dist/umd/graphjs.min.js | IIFE — exposes window.graphjs |

Build artifacts under dist/ are generated on demand (and on prepublishOnly); they are not committed. For a <script> tag, load the UMD bundle and use the graphjs global:

<script src="dist/umd/graphjs.min.js"></script>
<script>
  const graph = new graphjs.Graph();
  const layout = new graphjs.ForceDirected(graph, { center: { x: 400, y: 300 } });
</script>