Data displayGlass surface
PieChart
Shows part-to-whole relationships as an accessible donut or pie chart.
← All chart guides · Framework setup · Native counterparts
01
See it and copy it
Framework example
Explore the live chart, then open its code for Astro, React, or Elements.
Framework usage
1 series, 4 points. Values range from 8 to 46.
- Astro
- React
- Web Components
- Other
2,480 Projects
View chart data
| Category | Value | Share |
|---|---|---|
| Astro | 46 | 46% |
| React | 31 | 31% |
| Web Components | 15 | 15% |
| Other | 8 | 8% |
View PieChart code
Framework usage
Switch targets to compare the adapter code. This live preview runs the Astro example. React and Elements use their own behavior APIs; complete the matching framework setup before copying an example.---
import { PieChart } from '@santi020k/lumen-astro'
const series = {
data: [
{ label: 'Astro', x: 'astro', y: 46 },
{ label: 'React', x: 'react', y: 31 },
{ label: 'Web Components', x: 'elements', y: 15 },
{ label: 'Other', x: 'other', y: 8 }
],
id: 'frameworks',
label: 'Framework share'
}
---
<PieChart
aria-label="Package usage by framework"
caption="Illustrative framework share."
centerLabel="Projects"
centerValue="2,480"
heading="Framework usage"
{series}
/>import { PieChart } from '@santi020k/lumen-react'
const series = {
data: [
{ label: 'Astro', x: 'astro', y: 46 },
{ label: 'React', x: 'react', y: 31 },
{ label: 'Web Components', x: 'elements', y: 15 },
{ label: 'Other', x: 'other', y: 8 }
],
id: 'frameworks',
label: 'Framework share'
}
export const Example = () => (
<>
<PieChart
aria-label="Package usage by framework"
caption="Illustrative framework share."
centerLabel="Projects"
centerValue="2,480"
heading="Framework usage"
series={series}
/>
</>
)<script type="module">
import { defineLumenElements } from '@santi020k/lumen-elements/define'
defineLumenElements(['PieChart'])
</script>
<lumen-pie-chart id="example-pie-chart"
aria-label="Package usage by framework"
caption="Illustrative framework share."
center-label="Projects"
center-value="2,480"
heading="Framework usage"></lumen-pie-chart>
<script type="module">
"use strict";
const series = {
data: [
{ label: 'Astro', x: 'astro', y: 46 },
{ label: 'React', x: 'react', y: 31 },
{ label: 'Web Components', x: 'elements', y: 15 },
{ label: 'Other', x: 'other', y: 8 }
],
id: 'frameworks',
label: 'Framework share'
};
const chart = document.getElementById('example-pie-chart')
chart?.setAttribute('series', JSON.stringify([series]))
</script>Framework differences
Elements: Pass series as a JSON attribute or through the public element property. The Elements pie chart expects an array containing its series; Astro and React accept one series object.
When to use PieChart
Use when categories form one meaningful whole and readers need a broad sense of contribution rather than precise ranking.
- variant="donut" is the default; variant="pie" removes the center opening. Keep the legend visible so every slice has a readable identity.
- centerLabel and centerValue are supplied display content. Keep them consistent with the same reporting period and population as the slices.
Prepare the data
import type { LumenChartSeries } from '@santi020k/lumen-core'
const series = {
id: 'frameworks',
label: 'Framework share',
data: [
{ x: 'astro', label: 'Astro', y: 46 },
{ x: 'react', label: 'React', y: 31 },
{ x: 'elements', label: 'Web Components', y: 23 }
]
} satisfies LumenChartSeries- Astro and React accept one series object. The Elements series property accepts an array containing that series.
- Positive finite y values become slices. Their sum defines the whole and the calculated shares; percentages are not required as input.
- Use stable x identities and readable labels. valueFormatter formats measurements without changing the slice proportions.
Avoid misleading comparisons
- Zero, negative, missing, and nonfinite values do not become slices. Do not use a pie for signed balances or imply missing categories are measured zero.
- Many small or similarly sized slices are hard to compare. Use a BarChart or LollipopChart when exact ranking matters.
02
Choose your target
Add this component
Choose the package for your runtime. All adapters share the Lumen stylesheet. Use the matching registry command when you want a local wrapper for that framework.
pnpm add @santi020k/lumen-astropnpm add @santi020k/lumen-astrolumen add PieChartlumen add PieChartpnpm add @santi020k/lumen-reactpnpm add @santi020k/lumen-reactlumen add PieChart --target reactlumen add PieChart --target reactpnpm add @santi020k/lumen-elementspnpm add @santi020k/lumen-elementslumen add PieChart --target elementslumen add PieChart --target elementsGlass
Add the glass prop to apply the shared blur, saturation, border, and highlight tokens. Glass reads best over vivid content, so place the surface above imagery or color.
Framework share
1 series, 3 points. Values range from 13 to 58.
- Astro
- React
- Elements
1,280 Projects
View chart data
| Category | Value | Share |
|---|---|---|
| Astro | 58 | 58% |
| React | 29 | 29% |
| Elements | 13 | 13% |
View PieChart code
Framework usage
Switch targets to compare the adapter code. This live preview runs the Astro example. React and Elements use their own behavior APIs; complete the matching framework setup before copying an example.---
import { PieChart } from '@santi020k/lumen-astro'
const series = {
data: [
{ label: 'Astro', x: 'astro', y: 58 },
{ label: 'React', x: 'react', y: 29 },
{ label: 'Elements', x: 'elements', y: 13 }
],
id: 'frameworks',
label: 'Framework share'
}
---
<div class="docs-glass-demo">
<PieChart
aria-label="Framework share"
centerLabel="Projects"
centerValue="1,280"
glass
heading="Framework share"
{series}
/>
</div>import { PieChart } from '@santi020k/lumen-react'
const series = {
data: [
{ label: 'Astro', x: 'astro', y: 58 },
{ label: 'React', x: 'react', y: 29 },
{ label: 'Elements', x: 'elements', y: 13 }
],
id: 'frameworks',
label: 'Framework share'
}
export const Example = () => (
<>
<div className="docs-glass-demo">
<PieChart
aria-label="Framework share"
centerLabel="Projects"
centerValue="1,280"
glass
heading="Framework share"
series={series}
/>
</div>
</>
)<script type="module">
import { defineLumenElements } from '@santi020k/lumen-elements/define'
defineLumenElements(['PieChart'])
</script>
<div class="docs-glass-demo">
<lumen-pie-chart id="example-pie-chart"
aria-label="Framework share"
center-label="Projects"
center-value="1,280"
glass
heading="Framework share"></lumen-pie-chart>
</div>
<script type="module">
"use strict";
const series = {
data: [
{ label: 'Astro', x: 'astro', y: 58 },
{ label: 'React', x: 'react', y: 29 },
{ label: 'Elements', x: 'elements', y: 13 }
],
id: 'frameworks',
label: 'Framework share'
};
const chart = document.getElementById('example-pie-chart')
chart?.setAttribute('series', JSON.stringify([series]))
</script>API reference
Lumen-specific props and runtime attributes for the Astro primitive. Use the framework differences above and the copyable examples for React composition and Elements attributes; the public adapter types define their supported contracts.
| Attribute | Values | Default | Description |
|---|---|---|---|
| glass | boolean | "subtle" | "strong" | false | Applies the tokenized liquid-glass surface treatment with backdrop-filter fallbacks; "subtle" and "strong" adjust the fill intensity. |
| drilldown | boolean (Astro / Elements attribute) | false | Enables plotted datum actions and an equivalent native button disclosure, including with hidden tables. Astro requires UIPrimitives; Elements owns its lifecycle. |
| onDatumActivate | (detail: LumenChartDatumActivationDetail) => void (React) | - | Enables React datum actions and receives validated values with raw identities. Navigation and filtering remain application owned. |
| explore-data-label, datum-action-prefix, datumActionFormatter | string attributes, (context: string) => string property (Elements) | English labels | Localizes the Elements disclosure and datum actions. |
| labels.exploreData, labels.formatDatumAction | string, (context: string) => string | English labels | Localizes the actions disclosure and each contextual datum button. |
| series | LumenChartSeries | required | Provides one already-aggregated series whose positive finite data points become slices. |
| variant | "donut" | "pie" | "donut" | Uses a center opening by default or renders a traditional pie. |
| centerLabel, centerValue | string | ReactNode | - | Adds optional visual summary content in the donut center. |
| showLegend | boolean | true | Shows the color-independent category key. |
| showTable | boolean | true | Provides a revealable semantic table with category, value, and share columns. |
| valueFormatter | (value: number) => string | String | Formats values in SVG titles and the semantic table for Astro and React; Web Components expose the equivalent JavaScript property. |
| class, className | string | "" | Merges custom classes with the generated ui-* root classes. |
| ...native attributes | HTML attributes | - | Forwards standard attributes to the root element unless the component consumes them. |
Keyboard interactions
Keyboard behavior provided by the Astro UIPrimitives runtime for this component.
| Key | Action |
|---|---|
| Tab | Focus the actions disclosure and its native buttons in document order. |
| Enter, Space | Toggle the disclosure or activate the focused datum button. Actions remain available when the data table is hidden. |
Runtime events
CustomEvents dispatched by the Astro UIPrimitives runtime for this component.
| Event | Target | Detail | When |
|---|---|---|---|
| ui:chart-datum-activate | Astro chart figure or Elements data chart host | LumenChartDatumActivationDetail: series { seriesId, x, y, datumId? }, heatmap { x, y, value, datumId? }, range { x, low, high, datumId? } | Fires once after a plotted datum or its native action button is activated. Requires drilldown. Astro uses UIPrimitives, Elements owns its lifecycle, and React uses onDatumActivate instead. |