stat_group
Up to six KPIs with optional deltas.
Numbers worth reading at a glance. stat_group lays out up to six label/value pairs with optional deltas, in tabular figures so nothing dances as it updates.
Up to three share the plate as an even band. Beyond three they wrap, because four even columns on a phone is four truncated numbers.
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 to show a trend. One number with an arrow says less than six months of it: use chart.
Do not use it for a value against a limit either. "8.2 GB" beside "15 GB" makes the reader do the division; progress shows the proportion.
Props
Every block also carries type and a required fallback_text of 1 to 300 characters.
| Prop | Type | Required | Constraints |
|---|---|---|---|
items | array | Yes | 1 to 6 entries. |
items[].label | string | Yes | 1 to 60 characters. Rendered uppercase. |
items[].value | string | Yes | 1 to 30 characters. Formatted by you. |
items[].delta | string | No | Up to 20 characters. |
items[].trend | up | down | flat | No | up and down draw an arrow glyph, never a colour. flat draws no glyph. |
On the wire
{
"id": "blk_05",
"type": "stat_group",
"fallback_text": "Spent $1,284 across 9 orders, saving $96.",
"props": {
"items": [
{
"label": "Spent",
"value": "$1,284",
"delta": "18%",
"trend": "up"
},
{
"label": "Orders",
"value": "9",
"delta": "2",
"trend": "up"
},
{
"label": "Saved",
"value": "$96",
"delta": "no change",
"trend": "flat"
}
]
}
}Interaction
None. stat_group is a readout and has no interactive props.
States
| State | What the SDK draws |
|---|---|
| Loading | Three label-and-value placeholder pairs in the same even band. |
| Empty | An empty items array renders fallback_text inside the plate. |
| Long values | The value ellipsises before it wraps; the delta sits below it rather than beside it, so a long number never squeezes its own delta off the plate. |
Accessibility
trend is drawn as an arrow rather than a red or green tint, because a colour-only delta is unreadable to a third of colour-blind users. A delta with a direction announces it in words: "18%, up". A flat delta announces the figure alone.
fallback_text should state the numbers in a sentence, since the labels are uppercase fragments that read poorly on their own.