progress
Value against a limit, when the proportion is the answer.
How far through something the user is. progress shows up to six quantities against their ceilings: data used against an allowance, sessions completed against a goal, credit spent against a balance.
It exists because the proportion is the answer. "8.2 of 15 GB" tells you a number; a bar tells you whether to worry.
Re-rendered in the browser from the SDK’s own scales. Not a screenshot.
Rendered natively by the Flutter SDK and the Web SDK, both since 0.1.0.
When not to use it
Do not use it for a number with no ceiling. A count of orders is a stat_group, because there is nothing for the bar to fill toward.
Do not use it for a history of values over time, which is chart, and do not use it to show progress through a delivery, which is order_tracker: a delivery has named steps, not a percentage.
Props
Every block also carries type and a required fallback_text of 1 to 300 characters.
| Prop | Type | Required | Constraints |
|---|---|---|---|
title | string | No | Up to 120 characters. |
items | array | Yes | 1 to 6 entries. |
items[].label | string | Yes | 1 to 60 characters. |
items[].value | number | Yes | The current amount, in the same unit as max. |
items[].max | number | Yes | Greater than 0. The ceiling the bar fills toward. |
items[].value_label | string | No | Up to 40 characters. Overrides the default "value / max" readout. |
items[].caption | string | No | Up to 120 characters. |
On the wire
{
"id": "blk_18",
"type": "progress",
"fallback_text": "Two of five pairs toward a free pair.",
"props": {
"title": "Kicks Club",
"items": [
{
"label": "Pairs toward a free pair",
"value": 2,
"max": 5,
"value_label": "2 of 5",
"caption": "Resets every calendar year."
},
{
"label": "Store credit used",
"value": 18.5,
"max": 40,
"value_label": "$18.50 of $40"
}
]
}
}Interaction
None. progress is a readout and has no interactive props.
States
| State | What the SDK draws |
|---|---|
| Loading | A label bar over a track at the real height. |
| Zero | An empty track with its boundary intact, so the reader can tell zero from missing. |
| Over the maximum | The fill clamps at 100% rather than overflowing its track. |
| Empty | An empty items array renders fallback_text inside the plate. |
Accessibility
Each bar announces its label, its readout, its caption where it has one, and its percentage ("Pairs toward a free pair, 2 of 5, 40 percent"), so the proportion is spoken and not only drawn. The fill is drawn in ink, not your accent: a bar is a readout, and the accent marks what the reader can act on. The unfilled track is drawn on the plate rather than sunk and carries a 3:1 boundary of its own, because the fill's leading edge is the whole message.
fallback_text should state the proportion in words.