StatGroup
Every example on this page is live, drawn by the library's Storybook, where you can also change its props and see the result.
A row of labelled figures in equal-width columns, such as the readings along a thin band-shaped widget.
When the row gets too narrow, the group moves to fewer columns (the rest wrap onto another row)
and, by default, to smaller text, so no figure is cut off. Each label and value stays on one
line, ending in "…" if it has to. With columns="auto" the group stays one row instead and
leaves out the stats that do not fit.
Import
import {
StatGroup,
statGroupCapacity,
statTileHeight,
} from "~lib/data-display/stat-group";
Props
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
data | { label: string; value: string | number; change?: Change; helpText?: string; leading?: ReactNode }[] | Yes | N/A | The stats, in order |
columns | number | "auto" | No | Number of stats | Most columns in a row, or "auto" for one row of as many as fit |
minColumnWidth | number | No | 96 | Narrowest a column may get before the group uses fewer |
width | number | No | Measured | Width the group has, if your layout already knows it |
size | "auto" | "sm" | "md" | "lg" | No | "auto" | Text size; "auto" picks one from the column width |
align | "left" | "center" | "right" | No | "center" | Text alignment in each column |
divider | boolean | No | false | Draw a rule between columns |
Change: { value: number; trend: "up" | "down" | "neutral" }, the same as on
Stat. A stat's leading node, such as a coin's
Avatar crest, is drawn before its tile and centered on the value's line.
One Row of As Many As Fit
columns="auto" lays the stats out in a single row of as many columns as the width holds at
minColumnWidth each, sharing the width between them, and leaves out the stats past them, in
order. Nothing wraps onto a second row, so a group at the top of a small box never pushes the
blocks below it out. The browser decides how many fit from the box itself, so a saved render shown
in a narrower box drops more stats with no script.
statGroupCapacity(width, minColumnWidth?) returns how many stats such a row shows at a width, for
a plan that needs to know which of its figures made it in.
const { width } = useLayoutShape();
const shown = statGroupCapacity(width);
return (
<>
<StatGroup data={coins} columns="auto" />
{coins.length > shown && (
<Paragraph size="xs">+{coins.length - shown} more</Paragraph>
)}
</>
);
Tile Height
Every tile keeps each of its lines to one, so a row of tiles has a height a plan can count on.
statTileHeight(size, { change, helpText }) returns it in pixels, on the type scale of the frame
the widget is drawn for: the label and the value, plus a line for each of change and helpText
the tiles show. The widget design guide lists the heights on the scale every frame starts on. A
leading node no taller than the value's line leaves the height as it is.
const rowHeight = statTileHeight("sm", { change: true });
Examples
Band
With Trends
Narrow
With less room, the same four stats wrap onto two rows.
Dividers
Two Columns
Auto Columns
Four stats in a box that holds three: the fourth is left out rather than wrapped.