Stat Card

StatCard is the standard dashboard metric tile. Use it to surface a single KPI with optional context: a trend indicator (up/down/neutral), a comparison hint (e.g. “vs last month”), and an icon. Grid a set of them at the top of a dashboard to give users an instant overview.

Live demo

Usage

import { StatCard } from "@beacon/design-system";

// Basic
<StatCard label="Open Invoices" value="$142,500" />

// With trend
<StatCard
  label="Collected This Month"
  value="$38,200"
  delta="+12%"
  deltaTone="up"
  hint="vs last month"
/>

// Negative trend
<StatCard
  label="Overdue Balance"
  value="$9,400"
  delta="+$1,200"
  deltaTone="down"
  hint="vs last month"
/>

// With icon
<StatCard
  label="Active Projects"
  value="47"
  icon={<ProjectIcon />}
/>

Props

Prop	Type	Default	Description
label	ReactNode	—	Metric name shown above the value. Required.
value	ReactNode	—	Primary metric value (number, currency, percentage). Required.
delta	ReactNode	undefined	Change indicator (e.g. "+12%", "-$400").
deltaTone	StatDeltaTone	"neutral"	Colors the delta indicator.
hint	ReactNode	undefined	Small caption below the delta (e.g. "vs last month").
icon	ReactNode	undefined	Icon rendered in the top-right corner of the card.

StatDeltaTone values

Value	Meaning
"up"	Positive change. Renders in success green.
"down"	Negative change. Renders in danger red.
"neutral"	No directional meaning. Renders in muted content color.

Note: “up” and “down” are directional, not inherently good or bad. An increase in overdue balance is deltaTone="down" even though the number went up.

Design tokens used

Token	Role
--ds-color-surface-raised	Card background.
--ds-color-border-default	Card border.
--ds-color-content-default	Value text.
--ds-color-content-dim	Label text.
--ds-color-content-muted	Hint text and neutral delta.
--ds-color-status-success	Delta tone "up".
--ds-color-status-danger	Delta tone "down".
--ds-radius-md	Card border radius.
--ds-space-md	Card padding.

When to use

Dashboard summary rows, executive overview panels, and any context where a single metric and its trend need to be scannable at a glance. Grid four to six StatCards in a responsive row at the top of a dashboard page.