Donut
A donut shows how a few categories add up to one total. Each category is a slice, and the hole in the middle leaves room for that total.
When to use it
Use a donut for parts of a whole, with a handful of categories. Two to six slices stay readable. The centre total gives the reader the sum without a second chart.
A line is the chart for a time series. A bar is the chart for comparing totals, and for a long list of categories. Many thin slices turn the ring into a legend. The eight-source example on this page is there so you can see that limit.
Donut and pie
Pie and donut share one arc renderer. The type selects the chart and its defaults.
type: "donut" keeps the hole. mark.innerRadius defaults to 0.6, and mark.padAngle defaults to 2.
type: "pie" is the solid disk. mark.innerRadius defaults to 0, and mark.padAngle defaults to 0.
A closed hole is a pie. Set type: "pie".
Data
Each row is one category and one number. Point encoding.x at the category and encoding.y at the number. The channel is x and y. It is not theta or angle.
The numbers are amounts. ChartKit adds the slices it draws and gives each slice its share of that sum. You do not pass percentages. The spec below happens to add to 100. The yard example uses 86, 54, 41, and 28, and the fleet example uses 1840 and 1260.
A missing number, a zero, or a negative number is left out of the ring. validate() still accepts those rows. If every row is left out, render() returns an error chart, CK1006, instead of a ring.
When the hole is wide enough, the centre prints the sum of the drawn slices. A field name of value or y stays unlabeled. Any other field name is the unit under the total. A channel title replaces that name.
{
"encoding": {
"x": "label",
"y": { "field": "value", "title": "Sessions" }
}
}a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.
A spec that renders
This is the smallest donut. version, type, and a11y.alt are required. The hole and the gap come from the donut defaults, so mark can be omitted.
{
"version": "1",
"type": "donut",
"data": [
{
"label": "Search",
"value": 42
},
{
"label": "Direct",
"value": 28
},
{
"label": "Social",
"value": 18
},
{
"label": "Email",
"value": 12
}
],
"encoding": {
"x": "label",
"y": "value"
},
"a11y": {
"alt": "Search is the largest traffic source at 42 percent of sessions."
}
}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.
Hole
mark.innerRadius is the hole as a fraction of the radius, from 0 to 0.95. A donut defaults to 0.6. The centre total is drawn when the hole is wide enough to hold the number.
{
"mark": { "innerRadius": 0.6 }
}Gap
mark.padAngle is the gap between slices, in degrees, from 0 to 10. A donut defaults to 2. The renderer spends that many degrees on the gap and shares the rest of the circle by value.
{
"mark": { "padAngle": 2 }
}Slice labels and the legend
mark.labels draws a value on each slice. It defaults to false. mark.labelPosition sets the place. inside and center sit on the slice. outside draws a leader line. Setting labelPosition turns the labels on. With no mark.labelFormat, the label is the share of the total. Overlapping labels are skipped.
{
"mark": { "labels": true, "labelPosition": "outside" }
}legend is the key beside the ring. Omit it, or set true, and a donut with more than one slice shows a legend. false hides it. legend.position is top, right, bottom, left, or inside. When position is omitted, a chart at least twice as wide as it is tall puts the legend on the right. Otherwise the legend sits along the bottom. legend.values prints each slice's number next to its name.
{
"legend": { "position": "bottom" }
}Colours
Omit mark.palette and each slice takes the next theme colour. Set mark.palette to a list of colours, in slice order, to override that list. One to 24 colours. encoding.color can name a field on the row. It is the same channel other charts use.
{
"mark": {
"palette": ["#0f6e56", "#c45c26", "#1d4e89", "#5b4b8a"]
}
}Sort
mark.sort orders the slices. none keeps the data order and is the default. asc and desc sort by the number.
{
"mark": { "sort": "desc" }
}Start angle
mark.startAngle is where the first slice starts, in degrees. 0 is the top, and the slices run clockwise. The value can be from -360 to 360.
{
"mark": { "startAngle": 90 }
}Tooltip
tooltip is on for a donut when the key is omitted. Hovering a slice shows its name and its value. 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. Set those in the playground.
The rest of the spec
mark.cornerRadius rounds the slice corners, in px, from 0 to 40. mark.other folds slices under a fraction of the total into one bucket. mark.explode names slices to pull out, and mark.offset is how far, in px. Theme, number format, and the other shared keys live on the playground, with the full option list.