Getting started with vis-network
vis-network draws networks: sets of things (nodes) connected by relationships (edges). Family trees, dependency graphs, knowledge graphs, social networks, infrastructure maps — if it can be written as dots and lines, vis-network can draw it, and the drawing stays alive: visitors can drag nodes around, zoom, click to select, and watch the layout settle in real time.
This guide follows the same path as the example index: load the library, feed it data, then shape how it looks and moves. Every claim below has a live demo behind it — open the linked example and compare.
1. Loading the library: the standalone build
The fastest route is the standalone UMD build hosted on this site. It bundles vis-network together with its dependencies (including the DataSet from vis-data), so a single script tag gives you the global vis object:
<script src="https://vis.rapporteur.online/standalone/umd/vis-network.min.js"></script>Two other builds exist for other setups. The peer build (/peer/umd/vis-network.min.js) leaves the dependencies out, so you load vis-data yourself and can share one DataSet between vis-network and, say, vis-timeline. The ESNext build (/esnext/) ships modern modules for bundlers such as webpack or Vite, where you import only what you use. There is also a legacy build in /dist/, which older examples still reference. The four basic-usage demos show the same five-node graph built all four ways.
2. Nodes, edges and the DataSet
A network needs exactly two collections. Nodes are objects with a unique id and usually a label. Edges connect two node ids with from and to. Both live in a vis.DataSet, a small in-browser database that emits events when items change — add, update or remove an item and the graph redraws itself.
var nodes = new vis.DataSet([
{ id: 1, label: "Alice" },
{ id: 2, label: "Bob" },
{ id: 3, label: "Carol" }
]);
var edges = new vis.DataSet([
{ from: 1, to: 2 },
{ from: 2, to: 3 }
]);
var network = new vis.Network(
document.getElementById("mynetwork"),
{ nodes: nodes, edges: edges }, {});That is the whole pattern behind the basic usage demo. From there, the DataSet demos show dynamic updates, the dynamic filtering demo shows DataView subsets, and the DOT language demo shows feeding the network from Graphviz text instead of JavaScript objects.
3. Physics: why the graph moves
By default vis-network runs a force-directed simulation: edges behave like springs, nodes repel each other like charged particles, and the system settles into a readable layout on its own. Four solvers ship with the library — Barnes-Hut (the default, fast for large graphs), forceAtlas2Based, repulsion, and hierarchicalRepulsion for layered layouts. Gravity, spring length and damping are all tunable, and the physics configuration demo exposes every slider live, so you can feel what each parameter does before copying the values into your own options. When a graph must stay exactly where you put it, turn physics off after stabilisation, as the layout-without-physics demo does.
4. Layout: free-form or hierarchical
Free-form physics suits exploratory graphs. When the data is really a tree or a flow — org charts, dependency chains, state machines — switch to the hierarchical layout: set layout.hierarchical.enabled to true, pick a direction (UD, DU, LR or RL), and nodes arrange themselves in levels. The hierarchical layout demo and its methods companion cover direction, sorting and level separation. For reproducible free-form layouts, fix layout.randomSeed — the random seed demo shows the same graph settling identically on every load.
5. Where to go next
- Styling: node shapes, image nodes, edge arrows and multifont labels.
- Interaction: interaction events, in-graph editing (manipulation) and clustering for large graphs.
- Full applications: the Les Misérables co-occurrence graph, the World Cup network and the neighbourhood highlighting demo.
Common questions
My graph never stops moving. What is wrong?
Usually nothing is broken — the simulation keeps tiny forces alive. Lower the damping, raise stabilization.iterations, or disable physics once the stabilized event fires. Dense graphs with many crossing edges benefit from the forceAtlas2Based solver.
The canvas is blank but there are no errors.
Check the container first: vis-network needs an element with an explicit height, and it must exist before you construct the Network. Then check that every edge's from and to match a node id exactly — a single dangling edge id is the most common cause of a half-drawn graph.
How large a graph can it handle?
Thousands of nodes render comfortably; the performance demo renders 2,500 nodes with 12,500 edges. Beyond that, cluster aggressively, simplify labels, and consider rendering only the visible neighbourhood.
Can I save and restore a graph?
Yes — nodes and edges are plain data. The save and load demo serialises positions and data to JSON and rebuilds the network from it.