Treemap
A treemap shows parts of a whole as tiles. The area of a tile is the value. A flat list can group tiles by a color field. A hierarchy nests tiles inside their parent.
When to use it
Use a treemap when the question is which parts make up a total, and the parts are numerous enough that a pie becomes a ring of slivers. Inventory by material is twelve products under three materials, each split into a kind. Litres by cask is the same idea with three levels: orchard, apple, then cask.
A sunburst is the same hierarchy drawn as concentric rings. Color follows the top branch there too. A pie or a donut is the flat chart for a handful of parts. A bar is the chart when you are comparing amounts that do not need to add to one rectangle.
Treemap, sunburst, pie, and donut
Treemap and sunburst read the same trees. Nested children, encoding.path, or encoding.id with encoding.parent. A parent with no value is the sum of its leaves.
type: "treemap" packs that tree into rectangles. type: "sunburst" gives each level a ring. Pie and donut have no levels. Each row is one slice of a single disk.
Data
A flat treemap is one row per tile. encoding.x is the name. encoding.y is the size. encoding.color is an optional group. Tiles in a group share a series color, in lighter and darker tints, and sit together. The smallest spec points color at group. Wood, metal, and glass are the three groups.
{
"encoding": { "x": "name", "y": "size", "color": "group" }
}A nested treemap puts children on a node. Litres by cask and Where the crates sat are that shape. The leaf holds the number. The name field is still encoding.x, and the number is encoding.y. You can also pass flat rows with encoding.path, a list of fields from the root down to the leaf, or with encoding.id and encoding.parent.
A missing number, a zero, or a negative number is left out of the tiles. On a nested node, leave the value off and it becomes the sum of the leaves. If you set a parent value, it has to match that sum.
mark.palette does not apply to a treemap. It warns CK3010. Flat color comes from encoding.color and the theme series. Nested color follows the top branch.
a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.
A spec that renders
This is the smallest treemap. version, type, and a11y.alt are required. Three flat tiles and a color group need no mark.
{
"version": "1",
"type": "treemap",
"data": [
{
"name": "Oak",
"size": 8,
"group": "Wood"
},
{
"name": "Pine",
"size": 5,
"group": "Wood"
},
{
"name": "Steel",
"size": 6,
"group": "Metal"
}
],
"encoding": {
"x": "name",
"y": "size",
"color": "group"
},
"a11y": {
"alt": "Oak is the largest tile."
}
}Install core and the adapter for your framework. The menu in the sidebar picks the snippet. spec is the JSON above.
npm install @chartkitdev/core
npm install @chartkitdev/react
import { Chart } from "@chartkitdev/react";
export function Panel() {
return <Chart spec={spec} />;
}npm install @chartkitdev/core
npm install @chartkitdev/vanilla
import { mount } from "@chartkitdev/vanilla";
const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);npm install @chartkitdev/core
npm install @chartkitdev/vue
<script setup>
import { Chart } from "@chartkitdev/vue";
</script>
<template>
<Chart :spec="spec" />
</template>npm install @chartkitdev/core
npm install @chartkitdev/svelte
<script>
import { Chart } from "@chartkitdev/svelte";
</script>
<Chart {spec} />npm install @chartkitdev/core
npm install @chartkitdev/astro
---
import { Chart } from "@chartkitdev/astro";
---
<Chart spec={spec} />npm install @chartkitdev/core
npm install @chartkitdev/solid
import { Chart } from "@chartkitdev/solid";
export function Panel() {
return <Chart spec={spec} />;
}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} />;
});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;
}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 among existing treemap specs. Inventory by material is twelve products under material, then kind. Litres by cask is orchard, apple, then cask. Where the crates sat is row, stall, then good. Each one is three levels of nested children, so the level control changes the tiles on every example.
Levels
mark.depth is how many levels to draw under the root. Deeper nodes fold into that level. Omit it and the cap is 8, which is the whole tree for these examples. 1 draws the top branches only. 2 draws the top branch and its children. 3 reaches the leaves: the product, the cask, or the good.
{
"mark": { "depth": 2 }
}Legend
A treemap with more than one color group, or more than one top branch, shows a legend. Omit legend, or set true, and it sits on top. false hides it. legend.position is top, right, bottom, left, or inside. Litres by cask and Where the crates sat set bottom.
{
"legend": { "position": "bottom" }
}One group draws no legend. The tiles still take the series color.
Tooltip
tooltip is on for a treemap when the key is omitted. Hovering a tile shows its name and its value. A nested tile also shows the path, the share of its parent, and the share of the total. tooltip: false turns the card off. tooltip: true turns it on.
{
"tooltip": false
}{
"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.
The rest of the spec
The tile name is drawn only when the whole word fits. A name that does not fit is left off the tile and stays in the tooltip. The value is drawn when the rectangle is tall enough. There is no mark.labels switch on a treemap. mark.gap and mark.cornerRadius are accepted keys. The tiles on this page keep the layout's own padding and corner. Edit those keys in the playground. encoding.color.scale is the continuous color ramp, for a flat treemap whose color field is a number. Theme presets live on the playground, with the full option list.