Pie charts
Show a compact part-to-whole comparison.
Use pie for a small number of meaningful parts that form one whole. When precise comparison or many categories matter, use a sorted bar chart.
Part to whole
values reads a numeric field or counts rows. Repeated categories can aggregate with sum, average, min, max, or median with long values.
Donut
innerRadius is a ratio from 0 up to, but not including, 1. A positive value creates a donut without changing the chart’s semantics.
Slices are separated by a one-pixel stroke in the background color. Set stroke to change its color or width, or stroke: false to draw slices edge to edge. Widths must be positive. The same stroke applies to a single-slice pie or donut.
Do not put a second metric in the center just because there is a hole. If center text means something on its own, keep it in the surrounding product UI.
Labels and ordering
Labels may contain category, value, and percent, positioned inside, outside, or automatically. Automatic placement chooses a readable position from available arc geometry.
Use value ordering when ranking supports the story, or an explicit category list when color and slice order must remain stable across updates. Avoid relying on input row order accidentally.
Color and annotations
color.domain fixes category identity and color.range assigns explicit colors. Omit the range to use the selected theme.
Pie annotations anchor text to a category. They work for a small explanatory callout; native labels remain the right tool for systematic values or percentages.
Properties
| Field | Type | Default | Description |
|---|---|---|---|
version | "2026-09-26" | – | Required. The chart config version. |
type | ChartType | – | Required. The chart family. |
title | string | – | Chart title. |
subtitle | string | – | Supporting text beneath the title. |
caption | string | – | Caption below the chart for a source, methodology note, or date. |
accessibilityDescription | string | – | Accessible description of the chart's meaning. |
headerAlign | "start" | "center" | "end" | theme default | Horizontal alignment for the title and subtitle. Omit it to use the selected theme's alignment. |
locale | string | "en-US" | Locale identifier accepted by JavaScript Intl and associated with the chart content, such as en, pl, or zh-Hant. |
theme | ThemeName | "editorial" | One of 6 built-in themes. |
themeOverrides | ThemeOverrides | – | Override individual theme properties. |
category | PieCategoryRole | – | Required. Slice category field. |
values | PieValuesRole | – | Required. Slice values or count. |
order | CategoryOrder | – | Slice ordering policy. |
color | CategoricalColor | – | Slice color preferences. |
labels | PieLabels | – | Slice label content and position. |
innerRadius | number | 0 | Inner-radius ratio from 0 up to, but not including, 1. |
cornerRadius | number | theme default | Slice corner radius. |
stroke | false | Stroke | 1 | Slice separator color and width; false removes the separators. |
annotations | PieAnnotation[] | – | Slice annotations. |