PieChart
Parts of a single whole as slices, sorted largest-first. Honest for two or three shares and a rough read of the rest; past about five slices a `BarChart` compares them far better.
<UiPieChart :data="..." :categoryKey="..." :valueKey="..." :ariaLabel="..." />Needs the charts module
This component ships in @jgastager/bundy-ui/charts, a separate module so projects that never draw a chart don't carry the paint classes these need. Nothing extra to install — just add the module entry. See Charts.
Data
requireddata is one object per slice, and every value must be non-negative — a pie shows parts of one whole, and a negative part of a whole has no angle to draw.
- Chrome · 6,400 visits
- Safari · 2,800 visits
- Firefox · 1,200 visits
- Edge · 780 visits
Values must be non-negative — a pie shows parts of one whole, and a negative part isn't one. Negative and non-finite rows are dropped.
Hovering dims every slice except the focused one to 0.7 rather than drawing a ring on it — a ring is a dot, which reads as a stray mark sitting on the arc. The hit test is polar: the angle and distance under the pointer, not a bounding box.
The hover fade is a CSS transition over the library's own 250ms duration, so it costs nothing and honours prefers-reduced-motion. There's no animate prop and nothing tweens on a data change — the marks are plain SVG elements Vue patches directly.
Category key
requiredcategoryKey sets which field on each row labels the slice.
- Chrome
- Safari
- Firefox
- Edge
Value key
requiredvalueKey sets which field holds its numeric size.
- Chrome
- Safari
- Firefox
- Edge
ARIA label
requiredariaLabel is required, and worth writing carefully: slice angles are the hardest thing on any chart to read back, so the sentence should carry the finding rather than just naming the fields.
- Chrome
- Safari
- Firefox
- Edge
ARIA description
ariaDescription is the detail the label shouldn't carry.
- Chrome
- Safari
- Firefox
- Edge
Radius
radius rounds the corners of each slice. A little softens the wheel; too much starts eating into thin slices, which is how a small share disappears.
There's no innerRadius here on purpose. A pie with a hole in it is a donut, so that knob lives on DonutChart — one chart, one spelling.
Gap
gap is the space between slices, in degrees. Widen it to separate slices of similar colour; drop it to zero for an unbroken wheel.
Sort
sort orders the slices largest-first by default, which is what makes them comparable by eye. Turn it off when the rows already have a meaningful order — severity, plan tier, a funnel.
- Medium
- Low
- High
- Critical
- Critical
- High
- Medium
- Low
Slices are sorted largest-first by default. Comparing two similar angles is hard enough without them scattered around the circle.
Colors
colors pins a paint per slice, matched positionally to data — so it lines up with the rows as given, before any sorting.
- Critical
- High
- Medium
- Low
Colors are the library's own semantic ones — primary, secondary, success, warning, error, info, pending, neutral — and any shade of them, primary-400 through primary-950, exactly as the bg-* utilities spell them. Set color per series (or per item) to pin one; leave it unset to take the next slot of the default sequence. neutral and secondary are never handed out automatically, so an unlabelled series never lands on them.
Value format
valueFormat formats the values in the tooltip and the legend.
- Chrome · 6,400 visits
- Safari · 2,800 visits
- Firefox · 1,200 visits
- Edge · 780 visits
Tooltip
tooltip shows the tooltip on hover.
- Chrome
- Safari
- Firefox
- Edge
Legend
legend is on by default, and worth keeping: without it the slices carry their identity in colour alone, which only works when the surrounding copy names them.
The legend is on by default and should usually stay on: without it, slices carry their identity in colour alone.
Legend position
legendPosition sets where the legend sits relative to the plot.
- Chrome
- Safari
- Firefox
- Edge
Legend align
legendAlign places the key horizontally. Centre reads well under a wheel, which is itself centred, where start would leave it visibly off-axis.
- Chrome
- Safari
- Other
- Chrome
- Safari
- Other
- Chrome
- Safari
- Other
Legend orientation
legendOrientation flows the entries in a row or a column. vertical is the natural fit for a pie — one slice per line, beside or beneath the circle.
- Chrome · 6,400 visits
- Safari · 2,800 visits
- Firefox · 1,200 visits
- Edge · 780 visits
Height
height is the plot's height in pixels; the wheel is sized to fit inside it. It's ignored once aspectRatio is set.
- Chrome
- Safari
- Other
- Chrome
- Safari
- Other
Aspect ratio
aspectRatio sizes the chart from its container's width instead of a fixed height.
- Chrome
- Safari
- Firefox
- Edge
Loading
loading is a skeleton at the chart's exact height; an empty data array gets the empty state instead.
Fold the tail into “Other”
A pie stops being readable past five or six slices — the small ones become slivers no one can compare. Group the tail before it reaches the chart rather than shrinking the slices further.
- Chrome · 6,400 visits
- Safari · 2,800 visits
- Other · 1,980 visits
Good for two or three shares and a rough read of the rest. Past about five slices the small ones stop being distinguishable and a horizontal BarChart compares them far better; fold the tail into an "Other" row rather than adding more colours.
API Reference
Generated from the component's source — props, slots and emits as the component actually declares them.
Props
datarequiredRecord<string, unknown>[]ariaLabelrequiredstringEmits
focusChange[label: string | null]Types
interface ChartPlot {
x: number;
y: number;
width: number;
height: number;
/** Right edge, since marks need it more often than the width. */
right: number;
/** Bottom edge, which is also the x axis' baseline. */
bottom: number;
}type ChartColorName = ChartColorFamily | `${ChartColorFamily}-${ChartColorShade}`;