A key figure with the words that say what it counts, such as "412" under "Reporting live", set large so it reads at a glance in a report, a panel or on the kiosk.
When to use
Use Stat for a key figure with the words that say what it counts, such as "412" under "Reporting live", in a report, a panel or on the kiosk.
| Use instead | When |
|---|---|
| Delay | The figure is how late one vehicle or departure runs |
| Meter | The figure is a share within a range that a bar shows, such as the share of vehicles reporting live |
| FactList | Several facts about one thing, each a name and its value, sit in a list |
| ReportStrip | The figures are how many vehicles are in each data state |
| VehicleTable | Figures are compared row by row in a table |
| Count | A small count sits after a filter chip's or a tab's words |
Kongens Nytorv
Metro M1, M2 and M3.
Props
| Name | Type | Default | Description |
|---|---|---|---|
label* | ReactNode | — | What the figure counts, in a few words: "Reporting live", "Average delay". Required |
children | ReactNode | — | The figure, formatted as content design writes numbers: "412", "4 min", "≈ 30". Leave it out when no data says it, and Stat shows "—" and says "Unknown" |
unknownLabel | string | The locale's | Overrides "Unknown", heard in place of "—" when there is no figure |
slotProps | { label?: ComponentProps<"div", {}, HTMLProps> | undefined; value?: ComponentProps<"div", {}, HTMLProps> | undefined; } | — | Props for each part: label, value. |
label (required)ReactNode, default —- What the figure counts, in a few words: "Reporting live", "Average delay". Required
childrenReactNode, default —- The figure, formatted as content design writes numbers: "412", "4 min", "≈ 30". Leave it out when no data says it, and Stat shows "—" and says "Unknown"
unknownLabelstring, default The locale's- Overrides "Unknown", heard in place of "—" when there is no figure
slotProps{ label?: ComponentProps<"div", {}, HTMLProps> | undefined; value?: ComponentProps<"div", {}, HTMLProps> | undefined; }, default —- Props for each part:
label,value.
Use it
import { Stat } from '@mylder/perron'Ask your agent
search_docs({ query: "Stat" })Keyboard and ARIA
Stat has no keys of its own and is never focusable. A caller who makes it a link or button through render brings that element's own keys.
| Key | Does | From |
|---|---|---|
| None | Stat is not focusable or operable | Perron |
| Element | Role | Accessible name from | States announced |
|---|---|---|---|
root | None (generic div) | Not named; its text is read in place, label then figure | None |
label | None (generic div) | Its text, from label | None |
value | None (generic div) | Its text, from children | None |
The "—" in value, when unknown | Hidden: aria-hidden="true" | Not read | None |
The words in value, when unknown | Text, in VisuallyHidden | The owned string "Unknown", or unknownLabel | None |
What axe won't catch, from the contract, each with how this component meets it:
- Everything the eye is told, the ear is told, for every shape each prop accepts: the label and the figure are read as shown, label first; "—" is
aria-hiddenand the ear hears "Unknown" in its place (CR-4). No colour carries meaning: the figure iscolor.text.primary, and tertiary only for the "—" the words speak for. - Every landmark and named region has an accessible name: none here; the root is not a landmark or region.
- Every default label can be overridden:
unknownLabel. - Every shape the type accepts renders, in every variant:
labelandchildrenareReactNodes; a string, a number, an element and a list each render,0is a figure and not unknown (CR-3), andStat.test.tsxrenders each shape. TheDefaultstory gives a string label and a string figure. - A hidden copy kept for animation is
aria-hidden, and a collapsed region isinert: none here; nothing animates or collapses. The "—" isaria-hiddenbecause the words speak for it, not for animation. - Native semantics first: plain
divs, with no role and no ARIA beyondaria-hiddenon the "—"; the caller's own element throughrender, such as anli. - Focus moves in reading order and returns on close: Stat takes no focus and opens nothing.
- Every target is at least
size.target-minsquare: no target; Stat is not pressed. - Loops stop when the system asks for less motion: none here; Stat has no motion.
Owned strings
Every word Stat shows comes from the caller, through label and children, but for the one it announces when there is no figure.
| Key | English | Override | Seen or heard where |
|---|---|---|---|
unknown | "Unknown" | unknownLabel | value, heard in place of the aria-hidden "—" when there is no figure (CR-4) |
No key in packages/perron/src/locale/en.ts says it: delayUnknown, "Delay unknown", names a delay, so unknown is new, with a JSDoc line like its neighbours.
The new key is unknown, English "Unknown", with Danish "Ukendt", Swedish "Okänd" and Norwegian Bokmål "Ukjent": after the label it reads "Reporting live, Unknown", says no more than the data knows, as content design asks, and matches the "unknown" in "Delay unknown" in each language.
Do and don't
For a caller using the component, with the reason. Each row is a rule: a must row's Don't is never right, a should row's needs a reason, and Checked by says what catches the Don't in a caller's code.
| Rule | Level | Do | Don't | Checked by |
|---|---|---|---|---|
| DD-1 | must | Leave out children when no data gives the figure, so Stat shows "—" and says "Unknown" | Pass 0 or a guess when the figure is unknown: the brand never claims more than the data knows | review |
| DD-2 | should | Write the figure as content design does: "4 min" with a space, "≈ 30" for an estimate, "−1" with the true minus sign | Put the label's words inside the figure, such as "412 live": the figure stays short, and the label says what it counts | review |
| DD-3 | must | Name the figure in a few words in label: "Reporting live", "Average delay" | Leave label empty and rely on the layout to say what the number is: a figure without its name tells the ear nothing | review |
| DD-4 | must | Say a status in words beside the figure, or show it with a Meter or a SeverityLabel | Colour the figure through className to say it is good or bad: colour alone tells no screen reader and no colour-blind person | review |
| DD-5 | should | Use Delay for one vehicle's or departure's delay, and Text with variant='stat' for a figure inside a sentence | Use Stat in a row of a list or table: it is set large for a key figure, and rows compare figures in a data role | review |
| DD-6 | must | Announce a changed figure in the screen's own polite live region, when it changes state | Make a Stat a live region: a figure that updates every few seconds floods the screen reader | review |