Skip to content
Knotviz docs

Quickstart

Open a file, run the simulation, colour by a property, filter to what matters, export. Five minutes from here to actually understanding your graph.

Try with a 1,000-node sample A synthetic social network with 5 communities, 1,488 edges, and 5 property types (number, string, boolean, date, string[]). Everything below walks through this graph.

Want to use your own data? Every input-format page has a drop-in template and a try-it link. Same five steps apply.

1. Lay it out

Section titled “1. Lay it out”

Knotviz drops you straight into the canvas, but with random positions the graph is just a blob. The force simulation is what turns it into something useful — nodes repel every other node, connected nodes pull together, and after a few seconds clusters settle into distinct regions of the canvas.

  1. Press Space (or click Run in the left sidebar).
  2. Watch nodes fan out. The camera auto-fits every tick, so the whole graph stays in view as it reshapes.
  3. Press Space again when the layout settles — typically 3–5 seconds for a graph this size.
The 1,000-node sample graph after running the force simulation. Five community clusters are already visually distinct as loose clumps, connected by sparser bridge edges.

You can already see the five community clusters as loose clumps, connected by sparser bridge edges. That’s step 2 working: you now have structure on the screen. We’ll make it explicit in a moment.

If your graph never looks right, try tuning: Repulsion (wider spread), Friction (faster settle), or Link spring (tighter clusters) in the left sidebar, then hit Restart. Running the sim past ~2M nodes starts dropping frames.

Full reference

2. Explore

Section titled “2. Explore”

Direct canvas manipulation, no tool modes or menus to learn.

  • Scroll to zoom, drag to pan, Shift+scroll to rotate around the centre of mass
  • Hover a node to see its label, click to see every property it carries
  • Tick Highlight neighbours on hover in the left sidebar — now hovering any node keeps its direct neighbours opaque and dims everything else. Local structure without zooming in

Full reference

3. Visualize by node colours

Section titled “3. Visualize by node colours”

The graph has shape, but nothing tells you what that shape means. Colour is how you encode meaning — pick a property and every node re-paints to match its value.

  1. Open the Analyze panel on the right (the palette icon).
  2. Set Property → community. Each distinct community becomes a chip in the legend.
  3. Click Color in the Mode selector — Size is the default, so you need to switch. Every node re-paints to its community value.
  4. Swap palettes if you want — the Palette dropdown has 19 presets plus a custom editor.
The same graph, now coloured by community. Five distinct colour regions match the visual clusters — Tech yellow at the bottom-right, Sports green at the bottom-left, Arts purple at the top, and so on. The legend and Statistics panel on the right show the five communities with their counts.

The clusters you half-saw in step 1 are now explicit. The Statistics panel underneath the legend breaks down every distinct value — Sports: 246 (24.6%), Finance: 239 (23.9%), … — so you immediately know which segments dominate your graph and which are rare.

Numbers and dates behave differently from strings: they get a continuous gradient and a histogram. Try Property → joined to watch membership grow over time, or Property → age for a distribution with mean / p25 / p50 / p75 computed live.

4. Visualize by node size

Section titled “4. Visualize by node size”

Colour tells you what kind. Size tells you how much. Scaling each node by a numeric value turns the blob into a spatial histogram — you see the distribution laid across every cluster, not just a bar chart.

  1. Still in the Analyze panel, change Property → age.
  2. Click Size in the Mode selector. Each node scales to its age value; the Statistics panel switches to a histogram with total / mean / p25 / p50 / p75 computed live.
The same graph, now sized by age. Older users render as larger dots, younger as smaller. The Statistics panel on the right shows the age distribution as a histogram with live quartile readouts.

Only one encoding is active at a time, so picking Size drops the community colours — re-apply them via Property → community and Mode → Color when you’re done. For dates (joined), Size behaves the same way on the underlying epoch value.

Full reference

5. Filter down

Section titled “5. Filter down”

Colour shows you what’s there. Filter controls what to look at.

  1. Open the Filter panel (the sliders icon).
  2. Toggle the active filter to true. Node count at the top drops from 1,000/1,000 to 714/1,000 — the inactive 28.6% vanish, along with every edge attached to them.
  3. Stack filters to narrow further. age ≤ 30 AND tags includes "founder" AND community = Tech gives you the young Tech founders — a handful of nodes you can inspect one by one. Multiple filters combine with AND.
The graph with the active=true filter applied. 714 of 1,000 nodes match; the rest and their edges are gone from the canvas. The Filter panel on the right shows filters for every property type. The Analyze panel is still open in the middle with the community colouring intact.

Filter-hidden nodes don’t dim — they disappear. That’s deliberate: filters carve the view; search finds inside it. Each filter has its own enable checkbox so you can toggle on/off without losing the values you set — handy for A/B comparisons. String and string[] filters have a search box and select-all / clear-all shortcuts. Number and date filters have a log-scale toggle for power-law distributions.

Full reference

6. Export

Section titled “6. Export”

You’ve spent real time on the layout, the filter set, and maybe a custom palette. Save the state.

Click ↓ Download as JSON in the left sidebar (the body of the split-button). You get a single JSON file with every visible node’s current x/y position, every visible edge, every original property, and the nodePropertiesMetadata needed to re-open without losing information.

The chevron next to the button opens a format picker — JSON, CSV edge list, CSV nodes + edges (ZIP), GraphML, or GEXF — for round-tripping into other tools. Lossy formats (CSV edge list, GraphML) ask for confirmation first.

What’s not saved: filter state, colour / size encoding, palette choice. Those are view-only — re-apply them after re-opening. That keeps the export file small and interop-friendly.

Full reference

That’s the loop

Section titled “That’s the loop”

Load → lay out → explore → colour → size → filter → export. Everything else in Knotviz — search, per-property statistics, the five input formats, the 19 palettes — is variations on those seven moves.

Input formats Five formats, one internal model. What your file should look like, for each source.
Compare Gephi, Cosmograph, Graphistry — when each fits and when Knotviz does.
Limits Honest ceilings. Useful up to ~1M nodes. Past that, the tool loads but doesn't help.
Troubleshooting Specific failure modes and fixes. If something isn't loading or rendering right.