Animated org chart videos from JSON

People-ops sends a flat CSV of "name, title, reports_to" and asks for an org chart video for the new-hire onboarding deck. The diagram tool produces a static PNG. The screen-recorder version reveals the whole tree in one frame, which is the visual equivalent of dumping a stack trace. The viewer can't read it because there is nothing to read in order.

An animated org chart fixes that. Nodes pop in level-by-level. The CEO node lands first, then their direct reports, then the next layer, and so on. SVG connector lines draw themselves from parent to child as each level arrives. By the end of six seconds, the whole org is on screen — and the viewer has learned the shape.

What an "animated org chart" actually is

Three primitives:

1. A tree layout — each node positioned by its depth (vertical) and its in-level index (horizontal). The layout is deterministic; same JSON, same coordinates.
2. A level-by-level reveal — nodes at depth 0 appear first, then depth 1, then depth 2. Same easing per node, staggered start time.
3. Connector traces — SVG paths from each parent to each child, drawn with stroke-dashoffset from full to zero. The line draws downward as the child appears.

The connectors are the part that turns a "list of cards on a page" into an "org chart." Without them, the tree structure is invisible.

The data shape

The natural model for an org chart is a tree, not a table. Each node has a name, a title, and an optional accent flag for the highlight color. Children nest inline.

{
"name": "A. Mendez",
"role": "CTO",
"children": [
  { "name": "R. Park", "role": "Platform", "children": [
    { "name": "J. Liu",  "role": "Infra" },
    { "name": "S. Vega", "role": "API" }
  ]},
  { "name": "K. Tanaka", "role": "Render", "accent": true, "children": [
    { "name": "T. Brooks", "role": "Engine" }
  ]},
  { "name": "M. Okafor", "role": "Design", "children": [
    { "name": "E. Saito", "role": "Motion" },
    { "name": "N. Cole",  "role": "Brand" }
  ]}
]
}

The layout function is twenty lines and the only "algorithm" in the template. Each node gets (x, y) from its depth and its in-level position. The chart never knows the original CSV; it sees coordinates and renders boxes at them.

The node reveal

Each node starts at scale(0) and opacity 0, anchored at its center. A back-ease (with the overshoot cut to 1.4) gives the node a touch of weight on landing without going cartoonish. The reveal lasts about 550ms per node.

Stagger by depth, not by individual node. All level-1 nodes appear together; all level-2 nodes appear together. Per-node staggering at this size makes the chart look like it's loading rather than building. A flat-level reveal is the visual analog of "here is the whole team."

The connector traces

Each connector is an SVG <path> with an elbow — go down from the parent, hit the midpoint, go horizontal to the child's x-position, then drop into the child. M parentX parentY V midY H childX V childY is the entire path.

To draw the connector, compute its total length with getTotalLength() once, set stroke-dasharray to that length, and animate stroke-dashoffset from full to zero. The connector draws itself, parent to child, in about 600ms.

Time the connector to start just before its child node appears. By the time the connector finishes drawing, the node lands at its endpoint. The two animations should feel like one motion — the line pulls the node into place.

links.forEach(l => {
  const L = l.getTotalLength();
  l.style.strokeDasharray = L;
  l.style.strokeDashoffset = L;
});
addEventListener('hf-seek', (e) => {
  links.forEach(l => {
    const p = clamp01((e.detail.time - l.dataset.start) / 0.6);
    l.style.strokeDashoffset = l.dataset.len * (1 - easeOut(p));
  });
});

getTotalLength() is safe to call during render; the renderer waits for layout to settle before each hf-seek tick. See from DOM to MP4 for the wider picture on why DOM-state queries are deterministic in this pipeline.

Avoiding the spaghetti

An org chart with more than ~12 nodes per level becomes spaghetti. Two strategies, in increasing complexity:

• Collapse equivalent roles. Five engineers reporting to the same lead becomes one node "Engineers (5)" with a small count badge. The viewer doesn't need to see five identical cards.
• Multi-frame storytelling. Show the top of the tree first; in a second sequence, zoom into one branch. The render pipeline supports multi-shot videos — see the agent's camera for the framing.

The right move is almost always the first one. Org charts are about shape, not roster.

Parameterizing the chart

The three knobs that matter: depth pause (how long between levels), accent color (for the highlighted node), and the orientation. Top-down is the default; left-to-right is occasionally needed for very deep trees.

The pause knob is the one to tune first. For an onboarding video (where viewers are reading every label) push to 1.4 seconds. For a recap clip (where the structure is the point), pull down to 0.8 seconds.

Render to MP4

The HTML is the template; the JSON is the data; the CLI is the render. The same primitives — scale, opacity, dashoffset — are deterministic functions of t, so every frame is reproducible.

hyperframes render org.html --out org-chart.mp4 --duration 6 --fps 30

For a multi-tenant scenario (every team gets their own chart video), wire the JSON to a query and loop the render. The pattern is documented in programmatic video from data — most teams stand up a /org/[slug]/video.mp4 endpoint in an afternoon.

FAQ

How deep can the tree go before it stops working?

Three levels is the sweet spot. Four levels works if the third level has fewer than three nodes per branch. Beyond that, the chart becomes a hairball — collapse equivalent roles into "(N)" badges or split into multiple charts.

Can I render a left-to-right (horizontal) tree instead?

Yes. Swap the layout's x/y assignments and rewrite the connector paths to elbow horizontally (H midX V childY H childX). The reveal logic is identical. Horizontal trees work better for very deep hierarchies (engineering org charts at 5+ levels), but you lose the "top-down hierarchy" reading that vertical trees give for free.

How do I highlight a single team or branch?

Add an accent: true flag to the relevant nodes in the JSON. The template applies the accent color, and the highlighted nodes pop visually without changing the animation timing. For an even stronger highlight, fade non-accent nodes to 0.5 opacity once the full tree has landed.

What about dotted-line / matrix relationships?

Add a second link type with stroke-dasharray: 4 4 and a slower draw. Render dotted links after the solid hierarchy is complete — they're informational overlays, not structural. Anything else and the chart loses its primary reading direction.

Does this scale to an org of 500 people?

No. At that scale, you're not making an "org chart video," you're making a skip-level summary video. Render the top three levels (about 12–25 people) and let the rest live in your HRIS. Org chart videos are about teaching shape, not roster.

Where to go next

The tree-drawing primitive — node + connector with dash-trace — is the same pattern that powers product flowcharts, system architecture diagrams, and decision trees. Take the JSON in the playground, swap "name/role" for "feature/owner," and the same template renders a roadmap topology. The deterministic rendering doc explains why this all works frame-for-frame across machines.

Three levels, deterministic, ship the MP4 in an afternoon.