Stat

When to useLink to "When to use"

• Dashboards and overviews: the few numbers someone opens the page to see.
• A figure that leads somewhere: href makes the tile a link to the report behind it.

Use something else when:

• there are many facts about one thing (a record's details, a settings summary): DescriptionList
• the numbers are rows to compare: Table
• the figure is progress towards a goal: ProgressBar

UsageLink to "Usage"

import { Grid, Stat } from "@arshad-shah/cynosure";
import { users } from "@arshad-shah/cynosure/icons";

<Stat label="Revenue" value="£12,400" delta={{ value: "+12%" }} description="vs last month" />
<Stat label="p95 latency" value="184" unit="ms" delta={{ value: "-8%", tone: "success" }} />
<Stat label="Members" value="312" icon={users} href="/members" />

Change since last timeLink to "Change since last time"

delta draws an arrow and the change in a tone, and gives screen readers a sentence such as "up 12%". The direction comes from the value's sign (+ is up, - or − is down, anything else is flat) unless direction says otherwise. Up is success and down is danger; set tone when down is good news, as for costs or errors.

The spoken words are English by default. labels takes a function per direction, given the value without its sign:

<Stat
  label="Chiffre d'affaires"
  value="12 400 €"
  delta={{ value: "+12 %" }}
  labels={{ up: (v) => `en hausse de ${v}`, down: (v) => `en baisse de ${v}`, flat: (v) => `stable à ${v}` }}
/>

Units, icons and alignmentLink to "Units, icons and alignment"

unit is written after the value, smaller. icon adds a decorative IconTile at the start; align="center" puts it above and centres everything.

SizesLink to "Sizes"

size sets the value, the label, the icon tile and the card's padding together.

Several statsLink to "Several stats"

There is no StatGroup: put the stats in a Grid. When they form a set, make it a list with as="ul" on the Grid and as="li" on each Stat; a linked stat keeps its list item and puts the link inside it.

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Reading order: the label and the figures are a description list. The label is the term and the value, delta and description are its definitions, so a screen reader reads "Revenue, £12,400, up 12%, vs last month".
• Delta: the visible figure is hidden from assistive technology and a visually hidden sentence is read instead, so the direction never depends on colour or the arrow.
• Icon: decorative; the label names the stat.
• Link: one link named by the stat's text, with nothing interactive inside. Unsafe schemes such as javascript: are not linked.
• Digits are tabular, so figures in a row of stats line up.

TouchLink to "Touch"

A linked stat is a whole Card, well above the 44px target for coarse pointers, and a tap follows it. A static stat has nothing to press.

ThemingLink to "Theming"

The frame is a Card, restyled through the --cy-card-* tokens; the icon is an IconTile (--cy-icon-tile-*).

createTheme({ components: { stat: { valueWeight: "500" }, card: { radius: "8px" } } });

className and style are for layout only. Change the look through tokens so every product stays consistent.

RelatedLink to "Related"

Card · IconTile · Grid · DescriptionList · Table