Pie
A pie shows how a few categories add up to one total. Each category is a slice of a solid disk. There is no hole, and no total in the middle.
When to use it
Use a pie for parts of a whole, with a handful of categories. Two to six slices stay readable. 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 disk into a legend.
Pie and donut
Pie and donut share one arc renderer. The type selects the chart and its defaults.
type: "pie" is the solid disk. mark.innerRadius defaults to 0, and mark.padAngle defaults to 0.
type: "donut" keeps the hole. mark.innerRadius defaults to 0.6, and mark.padAngle defaults to 2. The hole is where the total is printed.
A hole is a donut. Set type: "donut". This page does not offer a hole control.
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. Share of revenue uses 42, 28, 18, 8, and 4. Plan mix uses 52, 24, 14, and 10. Loans by shelf uses 840, 310, 460, 520, 190, and 260.
A missing number, a zero, or a negative number is left out of the disk. validate() still accepts those rows. If every row is left out, render() returns an error chart, CK1006, instead of a pie.
a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.
A spec that renders
This is the smallest pie. version, type, and a11y.alt are required. The disk is solid and the slices meet, so mark can be omitted.
{
"version": "1",
"type": "pie",
"data": [
{
"label": "Search",
"value": 42
},
{
"label": "Direct",
"value": 28
},
{
"label": "Social",
"value": 18
},
{
"label": "Email",
"value": 8
},
{
"label": "Other ads",
"value": 4
}
],
"encoding": {
"x": "label",
"y": "value"
},
"a11y": {
"alt": "Search is the largest share of revenue. Other ads is the smallest slice."
}
}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.
Gap
mark.padAngle is the gap between slices, in degrees, from 0 to 10. A pie defaults to 0, so the slices meet. The renderer spends that many degrees on the gap and shares the rest of the circle by value.
{
"mark": { "padAngle": 1.5 }
}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 disk. Omit it, or set true, and a pie 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. Kiln hours sets that.
{
"legend": { "position": "bottom" }
}Colors
Omit mark.palette and each slice takes the next theme color. Set mark.palette to a list of colors, in slice order, to override that list. One to 24 colors. Loans by shelf sets six. encoding.color can name a field on the row. It is the same channel other charts use.
{
"mark": {
"palette": ["#0f6e56","#c45c26","#1d4e89","#a15c38","#5b4b8a","#8a6a2f"]
}
}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 pie 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. Loans by shelf sets both. Change those in the playground. Turning the card off and on again puts that object back.
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. mark.innerRadius opens a hole. That is a donut, so it is not a control on this page. Theme, number format, and the other shared keys live on the playground, with the full option list.