Stat Card

Quick start

Single-metric dashboard widget. Required props are value and label. Add delta for vs-prior-period change, trend for a sparkline, icon for a leading visual marker, variant to change density.

import { StatCard } from "@/components/stat-card"
import { DollarSign } from "lucide-react"

export function RevenueCard() {
  return (
    <StatCard
      value={12431}
      label="Revenue this month"
      icon={DollarSign}
      formatValue={(v) => `$${v.toLocaleString()}`}
      delta={{ value: 0.124 }}
      trend={[8200, 8800, 9100, 10200, 10900, 11500, 12100, 12431]}
    />
  )
}

Variants

• default — value + label + delta + sparkline. The canonical KPI strip card.
• compact — smaller value, no sparkline. Sidebar widgets and dense KPI grids.
• detailed — larger value + mandatory sparkline + larger icon. Hero KPI cards.

Delta polarity (`betterIsHigher`)

Default: betterIsHigher: true — a positive delta colors green, a negative delta colors red. Set false for cost / error metrics where ↑ is bad. The default delta.format is locale-aware Intl.NumberFormat percent — delta.value is a fraction (0.124 = +12.4%).

<StatCard
  value={errorRate}
  label="Error rate (last 24h)"
  delta={{ value: 0.08, betterIsHigher: false }}  // up = bad → red
/>

<StatCard
  value={signupCount}
  label="New signups this week"
  delta={{
    value: 1240,
    format: (v) => v.toLocaleString(undefined, { signDisplay: "exceptZero" }),
  }}
/>

Custom value rendering

Use renderValue for unit superscripts, tooltips, or any composite value treatment. Receives { value, loading }.

<StatCard
  value={42.7}
  label="Average response time"
  renderValue={({ value }) => (
    <span>
      {value.toFixed(1)}
      <span className="text-muted-foreground text-base ml-1">ms</span>
    </span>
  )}
/>

Sparkline

Pass trend as a flat number[]; the component renders a built-in pure-SVG sparkline (no charting peer dep). Cap at 100 points; larger arrays are uniformly downsampled. For non-line shapes (bars, dual-axis) use the renderTrend slot. The StatCardSparkline sub-component is exported separately for standalone use:

import { StatCardSparkline } from "@/components/stat-card"

<StatCardSparkline
  data={[42, 48, 55, 62, 68, 71, 67, 64]}
  className="h-8 w-32 text-primary"
/>

Loading + empty

loading=true renders a shape-matched skeleton — aria-busy+ sr-only loading announcement. Skeleton size matches the loaded variant so there's no layout shift on hydration. value=undefined renders labels.emptyValueLabel (default —) at the value position; same height, muted color.

i18n

Labels are overridable via the labels prop. Defaults are English; override deltaPrefix, deltaPeriod, loadingLabel, increaseLabel, decreaseLabel, emptyValueLabel. Number formatting via delta.format with a locale arg.

Accessibility

• Root is <dl> — screen readers announce label-value pairs natively.
• Sparkline + arrow are aria-hidden; the delta has an sr-only increaseLabel /decreaseLabelso SRs say "12.4% increase" not "12.4% up arrow".
• Linked variant uses overlay-link pattern: focus-visible ring on the card; the link element is transparent on top.
• Loading state is aria-busy="true" with sr-only loading announcement.