Stat

Install

pnpm exec vegastack-design verify stat

pnpm dlx shadcn@4.21.0 add @vegastack/stat

Usage

import {
  Stat,
  StatDelta,
  StatEmpty,
  StatLabel,
  StatValue,
} from "@/components/ui/stat";

<Stat>
  <StatLabel>Estimated ARR</StatLabel>
  <StatValue>$1M–$10M</StatValue>
</Stat>;

Dashboard tiles

size="lg" scales the value to text-2xl (24px, tabular) for stat tiles; add a StatDelta with intent="up" | "down" | "flat" — the sign/arrow in the copy carries the meaning, color is never the only signal.

Honest empties

When there is no value, render StatEmpty ("No connection", "No team") in the text-muted-foreground placeholder register — never a dash or a zero that would read as data. This mirrors the system-wide inline-empty tier (a muted placeholder span).

Anatomy

Stat is a compound component. Every exported part, with the data-slot it renders (generated from the canonical source):

Examples

The default scale suits record highlights; the tile preview exercises the large value scale and all three delta intents.

Linked stat tiles

When a count opens the list it counts, make the whole tile the link: an outline Item rendered as an <a>, with the label first and the value after it. The link's accessible name is the tile's text in reading order, so each tile announces as "Overdue tasks 3" with no aria-label to keep in sync. While counts load, a Skeleton stands in for the value and the label keeps naming the link.

Stat group

StatGroup is a compact row of inline stats — "Overdue 1 · Today 3 · Upcoming 12" — in one hairline-divided strip, for a home page or a dashboard header where four tiles would take a whole row. It follows its own width, not the viewport: one row of equal cells from 24rem, a 2×2 grid below. A cell with an href is a link through linkRender (your router's Link), named label first. undefined is loading (a skeleton holds the value's line), null is a failed read ("—" and errorLabel, never 0), and hideWhenAllZero renders nothing when every value is exactly zero.

Loading

StatSkeleton is a Stat while it loads — a label bar over a value bar at the Stat's own size — for a whole band of tiles before any count arrives.

API Reference

Stat

StatLabel, StatValue, and StatEmpty

These structural parts accept native <div> props and forward their refs to their respective elements.

StatDelta

StatSkeleton

StatGroup

Each item:

Accessibility

• Keep the label visible so the value has an adjacent human-readable name.
• Delta copy carries direction with words or a sign; color is supplementary.
• Use StatEmpty for missing data instead of a dash or a misleading numeric zero.
• Tabular numerals keep changing values aligned without changing their spoken representation.
• A StatGroup cell that is loading is aria-busy; its dash on a failed read is hidden from assistive technology, which hears errorLabel instead.

Do / Don't