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.

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

Import@chartkitdev/core/charts/pieBundle@chartkitdev/core/allFamilyLibrary
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.

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