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.y.title
{
  "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.

spec.json
{
  "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.

Import@chartkitdev/core/charts/donutBundle@chartkitdev/core/allFamilyCore
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.

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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "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": false
}
tooltip true
{
  "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.