Sunburst
A sunburst shows a hierarchy as concentric rings. The inner ring is the top branch. Each next ring splits that branch into its children. The angle is the value's share of its parent. Color follows the top branch.
When to use it
Use a sunburst when the question is how a total breaks down by level, and you want the levels to read as rings around one hole. Traffic by source is two rings: organic and paid, then the sources under each. The same cellar, in rings is three: orchard, apple, then cask.
A treemap is the same tree as tiles. Use it when area, not angle, should carry the value, or when the names are long. A pie or a donut is one level of parts. A sunburst with the hole closed is still a sunburst. The rings remain. A single disk is type: "pie".
Sunburst, treemap, pie, and donut
Sunburst and treemap share the hierarchy. Nested children, encoding.path, or encoding.id with encoding.parent. A parent with no value is the sum of its leaves.
type: "sunburst" maps each level to a ring. Siblings in a branch shift lightness and keep a gap. type: "treemap" maps each level to nested rectangles. Pie and donut have one ring of slices, and the angle is the whole encoding of the share.
Data
The usual spec is a tree of nodes. Each node has a name and either children or a number. Traffic by source uses name, children, and value. The same cellar, in rings points encoding.y at value so the number format applies. You can omit encoding when the nodes already use name and value.
Flat rows work too. encoding.path is the list of fields from the root down to the leaf. encoding.id and encoding.parent are the other flat form. An empty parent is a root.
Color is the top branch. Organic and paid are two colors. Search under organic keeps the organic color, shifted. There is no mark.palette on a sunburst. Setting it warns CK3010.
A negative value is an error on that node. Leave a parent's value off and it is the sum of its leaves. A parent value that does not match its children is an error.
a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.
A spec that renders
This is the smallest sunburst. version, type, and a11y.alt are required. One branch and two leaves are enough. The hole defaults to 0.28 of the radius, so mark can be omitted.
{
"version": "1",
"type": "sunburst",
"data": [
{
"name": "Ads",
"children": [
{
"name": "Search",
"value": 25
},
{
"name": "Social",
"value": 15
}
]
}
],
"a11y": {
"alt": "Search is most of Ads."
}
}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 sunburst specs. Traffic by source is two rings and the default hole. The same cellar, in rings and Shed, boat, job are three rings, and each sets its own hole.
Hole
mark.innerRadius is the hole, as a fraction of the radius, from 0 to 0.95. Omit it and a sunburst uses 0.28. The same cellar, in rings sets 0.42. Shed, boat, job sets 0.4. The hole prints the total when the disk is wide enough to hold it.
0 closes the hole. The rings stay, and the color still follows the top branch. That is not a pie and not a donut. Those types are a single ring of slices. This control stops at 0.75. A value above 0.85 warns CK3075.
{
"mark": { "innerRadius": 0.42 }
}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. 1 draws the top ring only. 2 adds the next ring. 3 reaches the casks and the jobs in the three-ring examples.
{
"mark": { "depth": 2 }
}Legend
A sunburst with more than one top branch shows a legend of those branches. Omit legend, or set true, and it sits on top. false hides it. legend.position is top, right, bottom, left, or inside. The same cellar, in rings and Shed, boat, job set bottom.
{
"legend": { "position": "bottom" }
}Tooltip
tooltip is on for a sunburst when the key is omitted. Hovering a slice shows its path, its value, its share of the parent, and its 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
Slice names are drawn on a ring that can hold them, or just outside it. A name that fits nowhere stays in the tooltip. There is no mark.labels switch, and mark.startAngle does not apply. Both warn CK3010. Theme presets live on the playground, with the full option list.