Tree

A tree draws one hierarchy as nodes and links. Each node is a dot with its name. A link joins a node to its parent. The layout is a tree, not a nested area and not a ring.

When to use it

Use a tree when the question is who connects to whom, and each node has one parent. Support org is that chart: Support splits into Inbox, Docs, and Billing, and each of those has its own work. Produce is the same kind of data drawn so the leaves line up.

A treemap turns the same hierarchy into tiles. The area is the value. A sunburst turns it into rings. A sankey is a weighted flow, and a node there can have several parents. This chart rejects a second parent. Boxes and photos are not drawn. The marks are dots and links.

Tree, treemap, and sunburst

All three read a hierarchy. Nested children, encoding.path, or encoding.id with encoding.parent.

type: "tree" places a dot for each node and a link to its parent. The gaps are the layout, not the value. mark.tree set to cluster lines the leaves up. That is the dendrogram.

type: "treemap" packs the tree into rectangles. type: "sunburst" gives each level a ring. Color on those charts follows the top branch. A tree colors the dots by that branch too, and the name is written beside the dot.

Data

The short form is id and parent. Point encoding.id at the node and encoding.parent at its parent. An empty parent is the root. Support org and Produce use that. Nested children on the row is the same shape a treemap uses. encoding.path is a flat path. It is legal here.

One root. Two roots are an error. Add a parent row that both roots point at. The chart does not invent that row. A cycle and a missing parent are errors too.

encoding.y is optional. When it is set, the number is part of the node's label, not a length. The layout does not size the gaps from the value. a11y.alt is required. One sentence, 10 to 500 characters. Name the root and the split that matters.

A spec that renders

This is the smallest tree. version, type, and a11y.alt are required. One root, two children, one grandchild. The layout is tidy, the root is on the left, and the links are curves, so mark can be omitted.

spec.json
{
  "version": "1",
  "type": "tree",
  "data": [
    {
      "id": "Root",
      "parent": ""
    },
    {
      "id": "A",
      "parent": "Root"
    },
    {
      "id": "B",
      "parent": "Root"
    },
    {
      "id": "A1",
      "parent": "A"
    }
  ],
  "encoding": {
    "id": "id",
    "parent": "parent"
  },
  "a11y": {
    "alt": "Root has two children. A has one child."
  }
}

Install core and the adapter for your framework. The menu in the sidebar picks the snippet. spec is the JSON above.

Import@chartkitdev/core/charts/treeBundle@chartkitdev/core/extraFamilyLibrary
React
npm install @chartkitdev/core
npm install @chartkitdev/react

import { Chart } from "@chartkitdev/react";

export function Panel() {
  return <Chart spec={spec} />;
}
Vanilla
npm install @chartkitdev/core
npm install @chartkitdev/vanilla

import { mount } from "@chartkitdev/vanilla";

const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);
Vue
npm install @chartkitdev/core
npm install @chartkitdev/vue

<script setup>
import { Chart } from "@chartkitdev/vue";
</script>

<template>
  <Chart :spec="spec" />
</template>
Svelte
npm install @chartkitdev/core
npm install @chartkitdev/svelte

<script>
  import { Chart } from "@chartkitdev/svelte";
</script>

<Chart {spec} />
Astro
npm install @chartkitdev/core
npm install @chartkitdev/astro

---
import { Chart } from "@chartkitdev/astro";
---

<Chart spec={spec} />
Solid
npm install @chartkitdev/core
npm install @chartkitdev/solid

import { Chart } from "@chartkitdev/solid";

export function Panel() {
  return <Chart spec={spec} />;
}
Qwik
npm install @chartkitdev/core
npm install @chartkitdev/qwik

import { component$ } from "@builder.io/qwik";
import { Chart } from "@chartkitdev/qwik";

export const Panel = component$(() => {
  return <Chart spec={spec} />;
});
Angular
npm install @chartkitdev/core
npm install @chartkitdev/angular

import { Component } from "@angular/core";
import { Chart } from "@chartkitdev/angular";

@Component({
  standalone: true,
  imports: [Chart],
  template: `<ck-chart [spec]="spec" />`,
})
export class Panel {
  spec = spec;
}
Custom element
npm install @chartkitdev/core
npm install @chartkitdev/element

import "@chartkitdev/element";

const chart = document.querySelector("chart-kit");
chart.spec = spec;

Each option below is a key on the spec. The demo changes that key and updates the chart and the snippet together.

Examples

The rail switches between two published trees. Support org is tidy, root on the left. Produce sets cluster and puts the root on top, so the leaves share one line. The gallery calls that second chart Leaves line up.

Layout

mark.tree is the algorithm. Omit it, or set tidy, and each leaf gets a slot. Branches share the gaps. That is the chart for an org or a topic tree. Support org uses it.

cluster pushes every leaf out to the same depth. The leaves line up. That is the dendrogram, and it is the chart for a clustering. Produce sets it. The type stays tree.

mark.tree
{
  "mark": { "tree": "cluster" }
}

Direction

mark.orient places the root. LR is the default: root on the left, children to the right. RL puts the root on the right. TB puts it on top, which is the direction an org chart usually wants. BT puts it on the bottom. Produce sets TB.

This is not mark.orientation. That key is horizontal or vertical on a bar. On a tree it warns, and repair maps horizontal to LR and vertical to TB.

mark.orient
{
  "mark": { "orient": "TB" }
}

Tooltip

tooltip is on for a tree when the key is omitted. Hovering a node shows its name, its parent, and its depth. When encoding.y is set, the value is in that label too. tooltip: false turns the card off. tooltip: true turns it on.

tooltip false
{
  "tooltip": false
}
tooltip true
{
  "tooltip": true
}

tooltip.fields chooses the rows in the card, and tooltip.position places it. Change those in the playground. Turning the card off and on again puts that object back. An example that omitted tooltip gets the key removed, so the default stays on.

The rest of the spec

mark.radial puts the root at the center and uses depth as the radius. It stays off until you set true. Labels collide once the leaves get numerous, so it is a playground choice, not the first tree. mark.depth caps how many levels are drawn. Omit it and the chart draws them, up to the default. mark.colorBy can color dots by depth instead of by the top branch.

A plain tree has no legend. A legend appears when encoding.color names a field, or when color is by depth. mark.collapsed hides the children of the ids you list. Theme presets live on the playground, with the full option list.