Feedback
ProgressGroup
One progress bar split into colored segments, with a legend — a breakdown of a total (disk usage, seats by plan, spend by category) rather than a single measure.
<UiProgressGroup :items="..." />Options
One block per prop — what it does, and what it looks like set.
Items
requireditems are the parts the bar is split into, drawn left to right in the order given — the component never sorts them. Each needs a value; a label names it in the legend, and color, icon and text are there when the defaults aren't enough.
- Design35%
- Engineering25%
- Research15%
value is an absolute amount measured against max, not a percentage — pass 24 of a 128 GB drive, not 19. Segments draw in array order and the component never sorts them, so put the biggest slice first yourself if that's the reading you want.
Progress is one measure moving toward completion (an upload, a job); ProgressGroup is one total split into parts (disk usage, seats by plan, spend by category). It has no indeterminate and no buffer — it isn't a loading indicator, and the two aren't interchangeable. Both have circle* variants, though: a group's ring lays its segments round it with the same hairline gaps as the bar.
Max
max is the total the segments are parts of — set it to the real figure (bytes, seats, hours) and pass raw values, rather than working the percentages out yourself. Segments adding up to less than it leave the remainder as empty track; segments adding up to more are scaled down in proportion so the bar still ends where it should.
- System19%
- Apps30%
- Media40%
- System21%
- Apps34%
- Media45%
Segments adding up to more than max are scaled down in proportion instead of overflowing the track, and showValue clamps at 100% — so an over-full bar reads as full rather than as 118%. The legend prints the share each segment is actually drawn at, which is why those shares still add up to 100 in that case.
Color
Left unset, each segment without a color of its own takes the next color in the built-in sequence — the same order the charts assign series colors in, so a breakdown bar and a pie chart of the same data agree on which slice is which. Set color to paint the whole bar one color instead, and set color per item to say what each segment means.
- Design35%
- Engineering25%
- Research15%
- Design35%
- Engineering25%
- Research15%
- Passed62%
- Flaky18%
- Failed9%
color has no default, and that's what makes the segments come out in different colors: each one without a color of its own takes the next entry in the built-in sequence (primary, pending, success, info, warning, error — the order the charts assign series colors in). Setting color paints every uncolored segment that one color, which collapses the breakdown into a single block — do it only when the items carry their own colors, or when the bar is deliberately one measure.
Variant
variant picks the track's weight, pairing one-to-one with Progress's variants so a group and a plain bar on one screen sit on the same rail. Past three or four segments lg is worth reaching for — the thin default leaves the smaller slices hard to pick out. The circle* variants lay the same segments round a ring, for a breakdown that has to fit in a square.
Size
size is the ring's diameter in pixels, for the circle* variants only. The line width stays that of the matching bar variant whatever the size, so a small ring in a sidebar and a large one on a dashboard read as the same weight.
Label
label sits above the bar and names the whole — the quota, the drive, the budget. The legend underneath names the parts, so this is the line that says what they're parts of.
- Design35%
- Engineering25%
- Research15%
Show value
showValue prints the segments' combined share next to the label — how full the total is, as against the legend's breakdown of what's filling it. It's clamped at 100%, so values overrunning max read as full rather than as 118%.
- System19%
- Apps30%
- Media40%
- System19%
- Apps30%
- Media40%
Legend
The legend is what makes a segmented bar readable — without it the colors carry no meaning. Turn it off only where the labels already live somewhere else on the screen, or where the bar is a glanceable summary rather than the breakdown itself.
- Design35%
- Engineering25%
- Research15%
A legend row prints the segment's share of the bar as a percentage. Set text on the item to print the figure in its own unit instead ('24 GB', '$1,840') — it replaces the percentage rather than sitting beside it, so put both in the string if you want both.
Legend orientation
horizontal wraps the entries into a row under the bar, which stays compact while the labels are short. vertical gives each one its own line with the shares aligned down the right edge — the shape to use for long labels, or when the breakdown is meant to be read figure by figure.
- System24 GB
- Applications38 GB
- Photos & video31 GB
- Documents12 GB
- System24 GB
- Applications38 GB
- Photos & video31 GB
- Documents12 GB
Examples
The component in real use: compositions that answer "how do I build X with this", rather than one prop at a time.
Storage breakdown
The shape this component is for: a real total, values in their own unit, an icon and a text per segment so the legend reads as a table of figures rather than percentages.
- System24 GB
- Applications38 GB
- Photos & video31 GB
- Documents12 GB
Seats by plan
A quota with room left in it. The segments stop short of the end because they add up to less than max — the empty track is the part still available, and showValue says how much of it is gone.
- Admins3
- Members22
- Invited6
Ring breakdown
The same storage breakdown on a ring: showValue moves inside it, label sits below, and the legend follows underneath — the shape for a card or a tile where a full-width bar has no room.
- System24 GB
- Applications38 GB
- Photos & video31 GB
- Documents12 GB
item slot
#item replaces the legend row for every segment, scoped with the item, its index and the percent of the bar it takes up. Give one segment a slot name of its own to override just that row and leave the rest on the default.
- Compute$1,84046%
- Storage$92023%
- Bandwidth$61015%
#item is written once and rendered for every segment, scoped with item, index and percent (the share of the bar it occupies, unrounded). Replacing the row makes the marker yours too — nothing else ties the legend entry to its color. To override just one row, give that item a slot name and pass <template #that-name>; the rest stay on the default.
API Reference
Generated from the component's source — props, slots and emits as the component actually declares them.
Props
itemsrequiredProgressGroupItem[]number100"primary" | "secondary" | "success" | "warning" | "error" | "info" | "pending" | "neutral""default" | "outline" | "lg" | "lg-outline" | "circle" | "circle-outline" | "circle-lg" | "circle-lg-outline"'default'stringbooleanfalse"horizontal" | "vertical"'horizontal'Slots
defaultitem.slot ?? 'item'Types
type Color = "primary" | "secondary" | "success" | "warning" | "error" | "info" | "pending" | "neutral";interface ProgressGroupItem {
/**
* What this slice of the total is — 'System', 'Documents', 'Team seats'. Shown in the legend.
*/
label?: string;
/**
* How much of the total this segment accounts for, in the same unit as `max`. A negative value
* counts as zero.
*/
value: number;
/**
* Colors this segment's fill and its legend marker. Left unset, the segment takes the group's
* `color` — or, when that's unset too, the next color in the built-in sequence.
*/
color?: Color;
/**
* Name of the icon shown in the legend in place of the colored dot, tinted the segment's color.
*/
icon?: string;
/**
* Trailing text in the legend, replacing the derived percentage — for the figure in its own
* unit ('24 GB', '8 seats') rather than as a share of the bar.
*/
text?: string;
/**
* Name of the slot rendering this entry's legend row, instead of the shared `#item` slot.
*/
slot?: string;
}interface Segment {
key: string | number;
color: Color;
width: number;
}interface Arc {
key: string | number;
color: Color;
start: number;
length: number;
}