Getting started

Install

Install the binding you want. Each one depends on the layers beneath it, so there is never a second package to remember.

npm install @klad/core

There is a fourth package, @klad/engine, but you only install it directly to write a binding for a framework that does not have one. It is the pure-logic layer — layout, viewport maths, the quadtree, the renderer, the worker protocol — and it touches no DOM.

A chart

import { createKlad, type Options } from '@klad/core'

const options: Options = {
  data: [
    { id: 'ceo', name: 'Jamie Fox', title: 'CEO' },
    { id: 'cto', parentId: 'ceo', name: 'Amy Chen', title: 'CTO' },
    { id: 'cfo', parentId: 'ceo', name: 'Priya Rao', title: 'CFO' },
  ],
  nodeSize: { w: 180, h: 64 },
  label: (item) => String(item.name ?? ''),
}

const chart = createKlad(document.getElementById('chart')!, options)

chart.on('nodeClick', ({ id, item }) => console.log('clicked', id, item))

// When the host element goes away:
chart.destroy()

The host element needs a size. The chart fills it and follows it with a ResizeObserver; a host that collapses to zero height gets a chart you cannot see, which is the single most common setup problem.

Shaping the data

data is a flat array. Parentage is parentId and nothing else — there is no nested children shape to convert to, which means the array that came back from your API is very often already the right shape.

[
  { id: 'ceo' }, //                      no parentId -> a root
  { id: 'cto', parentId: 'ceo' },
  { id: 'lead', parentId: 'cto' },
]

Everything beyond id and parentId is yours: name, title, avatarUrl, whatever your card renders and your label reads.

Several roots are fine — the layout places them side by side. A parentId naming an item that is not in the array does not throw; that item becomes a root and a warning event describes what happened, so a chart built from partial data still draws.

Next

• Node content — putting your own components on the nodes.
• Sizing — why nodeSize is declared, and what to do when a card changes height.
• Navigating — going to a node, opening the way to it, showing the route.