> ## Documentation Index
> Fetch the complete documentation index at: https://prefab.prefect.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# PieChart
> Visualize proportions with slices of a circle.
export const ComponentPreview = ({json, height, resizable, bare, hideJson, playground, children}) => {
const hostRef = React.useRef(null);
const handleRef = React.useRef(null);
const cardRef = React.useRef(null);
const containerRef = React.useRef(null);
const [previewWidth, setPreviewWidth] = React.useState(null);
const [isDragging, setIsDragging] = React.useState(false);
const [playgroundHref, setPlaygroundHref] = React.useState(null);
React.useEffect(function () {
if (!playground) return;
var isLocal = location.hostname === "localhost" || location.hostname === "127.0.0.1";
var path = isLocal ? "/playground" : "/docs/playground";
var url = new URL(path, window.location.href);
url.hash = "code=" + playground;
setPlaygroundHref(url.href);
}, [playground]);
var jsonStr = typeof json === "string" ? json : JSON.stringify(json, null, 2);
React.useEffect(function () {
if (cardRef.current) {
var card = cardRef.current.closest(".group");
if (card) card.classList.remove("group");
}
var host = hostRef.current;
if (!host || !json) return;
function mount() {
if (!window.__prefab || !host) return;
var dark = document.documentElement.classList.contains("dark");
handleRef.current = window.__prefab.mountPreview(host, jsonStr, {
dark: dark
});
if (bare && host.shadowRoot) {
var m = host.shadowRoot.querySelector("[data-prefab-mount]");
if (m) m.style.background = "transparent";
}
}
if (window.__prefab) {
mount();
} else {
if (!window.__prefabLoading) {
if (!window.__prefabReady) {
var s = document.createElement("script");
s.src = "/renderer.js";
document.head.appendChild(s);
}
window.__prefabLoading = new Promise(function (resolve) {
function check() {
if (window.__prefabReady) {
window.__prefabReady.then(resolve);
} else {
setTimeout(check, 10);
}
}
check();
});
}
window.__prefabLoading.then(mount);
}
var observer = new MutationObserver(function () {
var dark = document.documentElement.classList.contains("dark");
if (handleRef.current) handleRef.current.setDark(dark);
});
observer.observe(document.documentElement, {
attributes: true,
attributeFilter: ["class"]
});
return function () {
observer.disconnect();
if (handleRef.current) {
handleRef.current.unmount();
handleRef.current = null;
}
};
}, [json]);
function startResize(e) {
e.preventDefault();
var startX = e.clientX;
var startW = hostRef.current ? hostRef.current.offsetWidth : 0;
var maxW = containerRef.current ? containerRef.current.offsetWidth - 10 : startW;
setIsDragging(true);
function onMove(ev) {
var w = Math.max(260, Math.min(startW + (ev.clientX - startX), maxW));
setPreviewWidth(w);
}
function onUp() {
document.removeEventListener("mousemove", onMove);
document.removeEventListener("mouseup", onUp);
setIsDragging(false);
}
document.addEventListener("mousemove", onMove);
document.addEventListener("mouseup", onUp);
}
if (bare) {
return ;
}
if (resizable) {
return
{previewWidth &&
{previewWidth}px
}
{playgroundHref && }
{children}
;
}
return
{playgroundHref && }
{children}
;
};
PieChart shows how parts relate to a whole. Unlike the other chart types, it doesn't use series — instead you specify which data field holds the numeric values (`data_key`) and which holds the labels (`name_key`). Set `inner_radius` to turn it into a donut chart.
## Basic Usage
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components.charts import PieChart
data = [
{"browser": "Chrome", "visitors": 275},
{"browser": "Safari", "visitors": 200},
{"browser": "Firefox", "visitors": 187},
{"browser": "Edge", "visitors": 173},
{"browser": "Other", "visitors": 90},
]
PieChart(
data=data,
data_key="visitors",
name_key="browser",
show_legend=True,
)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"type": "PieChart",
"data": [
{"browser": "Chrome", "visitors": 275},
{"browser": "Safari", "visitors": 200},
{"browser": "Firefox", "visitors": 187},
{"browser": "Edge", "visitors": 173},
{"browser": "Other", "visitors": 90}
],
"dataKey": "visitors",
"nameKey": "browser",
"height": 300,
"innerRadius": 0,
"showLabel": false,
"paddingAngle": 0,
"showLegend": true,
"showTooltip": true,
"animate": true,
"valueFormat": "auto"
}
}
```
## Donut Chart
Set `inner_radius` to a value greater than 0 to hollow out the center. This creates a donut chart, which can feel cleaner and leaves room for a central label or statistic.
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
PieChart(
data=[
{"browser": "Chrome", "visitors": 275},
{"browser": "Safari", "visitors": 200},
{"browser": "Firefox", "visitors": 187},
{"browser": "Edge", "visitors": 173},
{"browser": "Other", "visitors": 90},
],
data_key="visitors",
name_key="browser",
inner_radius=60,
show_legend=True,
)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"type": "PieChart",
"data": [
{"browser": "Chrome", "visitors": 275},
{"browser": "Safari", "visitors": 200},
{"browser": "Firefox", "visitors": 187},
{"browser": "Edge", "visitors": 173},
{"browser": "Other", "visitors": 90}
],
"dataKey": "visitors",
"nameKey": "browser",
"height": 300,
"innerRadius": 60,
"showLabel": false,
"paddingAngle": 0,
"showLegend": true,
"showTooltip": true,
"animate": true,
"valueFormat": "auto"
}
}
```
## Labels
Set `show_label=True` to display a label on each slice, making values readable without tooltips.
```python Python {5} icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
PieChart(
data=data,
data_key="visitors",
name_key="browser",
show_label=True,
show_legend=True,
)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"type": "PieChart",
"data": [
{"browser": "Chrome", "visitors": 275},
{"browser": "Safari", "visitors": 200},
{"browser": "Firefox", "visitors": 187},
{"browser": "Edge", "visitors": 173},
{"browser": "Other", "visitors": 90}
],
"dataKey": "visitors",
"nameKey": "browser",
"height": 300,
"innerRadius": 0,
"showLabel": true,
"paddingAngle": 0,
"showLegend": true,
"showTooltip": true,
"animate": true,
"valueFormat": "auto"
}
}
```
## Spaced Slices
Set `padding_angle` to add space between slices, visually separating each segment.
```python Python {6} icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
PieChart(
data=data,
data_key="visitors",
name_key="browser",
inner_radius=60,
padding_angle=5,
show_legend=True,
)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"type": "PieChart",
"data": [
{"browser": "Chrome", "visitors": 275},
{"browser": "Safari", "visitors": 200},
{"browser": "Firefox", "visitors": 187},
{"browser": "Edge", "visitors": 173},
{"browser": "Other", "visitors": 90}
],
"dataKey": "visitors",
"nameKey": "browser",
"height": 300,
"innerRadius": 60,
"showLabel": false,
"paddingAngle": 5,
"showLegend": true,
"showTooltip": true,
"animate": true,
"valueFormat": "auto"
}
}
```
## Tooltip Formatting
Use `value_format` to format tooltip values with the same pipe strings as Prefab expressions and data table columns. Percent formatting expects fractional values, so `0.42` renders as `42%`.
```python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components.charts import PieChart
data = [
{"category": "Compute", "share": 0.42},
{"category": "Storage", "share": 0.24},
{"category": "Network", "share": 0.18},
{"category": "Support", "share": 0.16},
]
PieChart(
data=data,
data_key="share",
name_key="category",
value_format="percent:1",
show_legend=True,
)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"type": "PieChart",
"data": [
{"category": "Compute", "share": 0.42},
{"category": "Storage", "share": 0.24},
{"category": "Network", "share": 0.18},
{"category": "Support", "share": 0.16}
],
"dataKey": "share",
"nameKey": "category",
"height": 300,
"innerRadius": 0,
"showLabel": false,
"paddingAngle": 0,
"showLegend": true,
"showTooltip": true,
"animate": true,
"valueFormat": "percent:1"
}
}
```
## API Reference
Data as a list of dicts, or a `{{ field }}` interpolation reference.
The data field containing numeric values to plot as slice sizes.
The data field containing labels for each slice.
Chart height in pixels.
Inner radius in pixels. Set greater than 0 for a donut chart.
Show a label on each slice.
Angle in degrees between slices.
Show a legend below the chart.
Show tooltips on hover.
Format tooltip values with an expression pipe such as `currency`, `currency:EUR`, `percent:1`, or `compact:0`.
Additional Tailwind CSS classes.
## Protocol Reference
```json PieChart theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"type": "PieChart",
"id?": "string",
"onMount?": "any",
"data": "object[] | string (required)",
"dataKey": "string (required)",
"nameKey": "string (required)",
"height?": "300",
"innerRadius?": 0,
"showLabel?": false,
"paddingAngle?": 0,
"showLegend?": true,
"showTooltip?": true,
"animate?": true,
"valueFormat?": "string",
"cssClass?": "string"
}
```
For the complete protocol schema, see [PieChart](/protocol/pie-chart).