Components

Pie Chart

Show how a small set of categories contributes to a whole. Switch between pie, donut, and semicircle views with the same data and inspection controls.

Install

npx mario-charts@latest add pie-chart

Playground

Compare proportions, variants, loading, and edge cases.

Settings

The same chart through every state.

DataStateVariantSlice cornersInner radius · 60%

Show legendShow center total

Animate

Revenue by plan

Illustrative monthly revenue · USD

Waiting for chart space

Hover or tap to inspect. Use arrow keys to move between slices and Enter to select.

tsx

import { PieChart } from "@/components/charts/pie-chart";

const data = [
  { plan: "Starter", revenue: 1800 },
  { plan: "Pro", revenue: 4200 },
  { plan: "Team", revenue: 3200 },
  { plan: "Enterprise", revenue: 2800 },
];

export function RevenueByPlan() {
  return (
    <PieChart
      data={data}
      label="plan"
      value="revenue"
      variant="donut"
      cornerRadius={8}
      showLegend
      valueFormatter={(value) => "$" + value.toLocaleString("en-US")}
      ariaLabel="Revenue share by plan"
    />
  );
}

Data and state contracts

A known whole

Use finite, nonnegative quantities in the same unit. Missing or malformed values make the total unknown and show an error. Normalize them explicitly before rendering.

Zero has no slice

Zero rows remain in the optional legend. They add no angle and do not change the colors or callback indices of later rows. An all-zero total displays an empty state.

A stable frame

Pie, donut, and semicircle use the requested height in every state. Retain data during refresh to keep the exact slice geometry. Without data, loading uses neutral placeholders.

Small shares stay accessible

Use arrow keys to inspect small slices that are difficult to target. For many categories or precise comparisons, a bar chart may communicate the differences more clearly.

Upgrading? The tooltip’s rawValue now contains the original numeric field instead of the category label. Use label for the category. Full circles start at the top; semicircles start at the left.

API Reference

Prop	Type	Default	Description
`data`Required	readonly T[]	—	Observations with finite, nonnegative values. Zero rows have no slice.
`value`Required	keyof T	—	Numeric value key. Missing and malformed values produce an error.
`label`Required	keyof T	—	Category label key; labels remain available through inspection.
`variant`	'pie' \| 'donut' \| 'semi'	'donut'	Full pie, donut, or upper semicircle, all within the requested frame height.
`innerRadius`	number	0.6	Fraction of outer radius, from 0 inclusive to 1 exclusive. Ignored for pie.
`cornerRadius`	number	0	Slice corner radius in pixels. Use 0 for flat edges or 8 for rounded corners. Automatically limited for small slices and thin rings; full circles have no corners.
`centerContent`	ReactNode \| ((data: { total: number; items: readonly T[] }) => ReactNode)	—	Content inside the donut or semicircle hole. Keep it compact; it is constrained to the hole.
`height`	number	300	Total height including the optional legend, in every variant and state.
`colors`	readonly string[]	DEFAULT_COLORS	Colors follow original row indices, including when zero rows are skipped.
`showLegend`	boolean	false	Show category values, including zeros, in a scrollable legend within the frame.
`loading`	boolean	false	Retain data for a skeleton matching the exact slice geometry. Without data, use neutral placeholder slices.
`error`	string \| null	null	Show an error while retaining the chart frame.
`animation`	boolean	true	Reveal slices around the circle with a smooth sweep. The center stays fixed; keyboard focus completes the reveal immediately. Respects reduced motion.
`onSliceClick`	(data: T, index: number) => void	—	Select a slice with pointer or Enter/Space. Receives the original row and index.
`tooltipRenderer`	TooltipRenderer<PieChartTooltipData<T>>	—	Custom tooltip with label, parsed value, original rawValue, percentage, color, and original index.
`valueFormatter`	(value: number) => string	—	Format values in tooltips, the legend, and accessible slice labels.
`percentageFormatter`	(percentage: number) => string	—	Format a percentage from 0 to 100. Defaults to one decimal at most; tiny shares use <0.1% and nearly complete shares use >99.9%.
`ariaLabel`	string	—	Accessible chart name.
`description`	string	—	Additional context, units, or caveats announced with the chart.
`className`	string	—	Classes applied to the outer frame in every state.