Charts
GaugeChart
A single bounded value on a dial — an arc over a restricted sweep, with the exact number in the middle. Good for a status summary; a `Progress` bar is the better read when the value needs comparing to another one.
<UiGaugeChart :modelValue="..." :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.
Model value
requiredmodelValue is the reading. It's clamped into min…max before it's drawn, so an out-of-range value pins the arc rather than overshooting it.
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.
ARIA label
requiredariaLabel is required. A gauge is a single number drawn as an angle — this is what makes that number available at all without sight.
ARIA description
ariaDescription is the detail the label shouldn't carry — a threshold, a trend, what happens at the top of the range.
Min
min is the bottom of the range. Raise it when zero isn't a meaningful floor — a temperature, a score that starts at 200 — so the arc spends its length on the part that varies.
model-value is clamped into min…max before drawing, so an out-of-range value shows a full or empty dial rather than an arc that wraps around.
Max
max is the top of the range, and what the percentage readout is a percentage of. Set it to the real ceiling rather than the largest value you happen to have.
Label
label is the text under the readout, naming what's being measured. Without it the gauge is a number with no subject.
Display
display replaces the center readout wholesale. Reach for it when the number to show isn't a function of the value — a grade, a status word, a fraction.
Value format
valueFormat formats the center readout, which otherwise shows the percentage of the range.
Sweep
sweep sets how far around the circle the track runs, centred on twelve o'clock. 270 is the classic dial; 180 is the half-circle that sits under a stat tile without wasting the height a full dial needs.
sweep="180" is a half-circle that stacks tightly in a row of stat tiles; the default 270° is the classic dial.
Thickness
thickness is the arc's width as a fraction of the radius. Thin reads as precise, thick as a status light — pick from how the number is meant to be used, not from how much room there is.
Color
color paints the filled arc. Binding it to a threshold is the usual move: the gauge then changes meaning as the value crosses one, without any extra chrome.
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.
Track color
trackColor paints the unfilled remainder. Lighten it on a raised surface so the track doesn't read as a hole punched through the card.
Height
height is the plot's height in pixels; the arc is sized to fit inside it. It's ignored once aspectRatio is set.
Aspect ratio
aspectRatio sizes the gauge from its container's width instead of a fixed height.
Loading
loading is a skeleton at the gauge's exact height, so a tile doesn't resize when the reading lands.
When a Progress is the better read
A gauge spends a lot of space on one number. If the value is a straightforward completion — a form, an upload, a quota bar in a settings row — a Progress says the same thing in a line.
The readout in the middle isn't decoration — arc length gives a rough read at best, so the exact number is what the viewer actually takes away.
Good at "roughly where in the range am I", poor at comparison: two dials side by side are much harder to rank than two bars. If the value needs comparing to another one, use Progress.
API Reference
Generated from the component's source — props, slots and emits as the component actually declares them.
Props
number270Types
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}`;