docs / patterns / stat-card

StatCard

one metric in a tile: a big value, a quiet unit, and a colored trend. one featured tile per grid; the rest stay smaller.

intensity · structuresrsc · server

provenance

shaped from personal-website

layer

core / patterns

intensity

structures · organizes a region, stays out of the content

composition

grids of two to four on a dashboard, or inside DashboardGridthe spark slot takes a sparkline that stretches to the tile widthnot a marketing proof strip, that is StatBentono actions inside. a metric that opens something wraps in a link

a11y

the icon and trend glyph are aria-hidden · the trend meaning is duplicated by the note text, never color alonejest-axe

dependencies

Card from the same package
live demo · try it out
Revenue
48.2k
8.1% MoM
Response time
128ms
12% faster
Active users
2,940
steady
Error rate
0.03%
within SLO
featured · tone
Stars
12.4k
all-time
Uptime
99.98%
30-day

props

proptypedefaultnotes
labelReact.ReactNode—the uppercase metric label at the top.
valueReact.ReactNode—the figure. mono, tabular, the loudest thing in the tile.
unitReact.ReactNode—quiet suffix beside the value, e.g. ms, %.
noteReact.ReactNode—the footnote beside the trend glyph.
iconReact.ReactNode—decorative glyph chip in the top-right corner.
trend"up" | "down" | "flat"—colors the note and prepends a directional glyph. up is success, down is danger.
size"sm" | "md""md"padding and value size.
featuredbooleanfalseblows the tile up to a hero stat with a much larger numeral.
tone"neutral" | "accent" | "accent-alt""neutral"tints the border and colors the value.
surfaceCardSurface"elevated"how the tile sits on the page. passed through to Card.
sparkReact.ReactNode—slot for a sparkline or mini-chart, stretched to fill.

get it

bun add @usva-ui/reactcopy
usagecopy
import { StatCard } from "@usva-ui/react/patterns/stat-card";

<StatCard
  label="Response time"
  value="128"
  unit="ms"
  trend="down"
  note="12% faster"
/>