Components

Stat

A single metric rendered as a typographic unit — an eyebrow label, a large value, and an optional trend line. The atom every KPI surface is built from.

Install

npx shadcn@latest add @alix/stat

Preview

Net revenue$248.6M

+12.4%vs. FY24

Avg. utilisation87.3%

+2.1ptvs. Q2

Usage

<Stat
  label="Net revenue"
  value="$248.6M"
  delta={<Delta value="+12.4%" direction="up" intent="positive" />}
  caption="vs. FY24"
/>

Examples

Value size scale

Use size to set hierarchy when multiple standalone metrics sit in the same view.

Open risks14

this week

Pipeline$84.2M

+6.8%vs. plan

Utilisation87%

+2ptvs. Q2

<Grid columns={3} gap="lg" align="end">
  <Stat size="sm" label="Open risks" value="14" caption="this week" />
  <Stat
    label="Pipeline"
    value="$84.2M"
    delta={<Delta value="+6.8%" direction="up" intent="positive" />}
    caption="vs. plan"
  />
  <Stat
    size="lg"
    label="Utilisation"
    value="87%"
    delta={<Delta value="+2pt" direction="up" intent="positive" />}
    caption="vs. Q2"
  />
</Grid>

Alignment choices

Change align when a metric needs to sit flush left, centered, or flush right inside a fixed area.

Start64%

Center78%

End92%

<Grid columns={3} gap="sm">
  <div className="border border-border p-4">
    <Stat align="start" label="Start" value="64%" />
  </div>
  <div className="border border-border p-4">
    <Stat align="center" label="Center" value="78%" />
  </div>
  <div className="border border-border p-4">
    <Stat align="end" label="End" value="92%" />
  </div>
</Grid>

Panel summary strip

Panel supplies the frame while Separator keeps a compact group of bare Stats readable.

Engagement snapshot

Current week

Active38

+4engagements

At risk6

-2this week

Awaiting review11

items

<Panel title="Engagement snapshot" description="Current week">
  <div className="grid gap-5 sm:grid-cols-[1fr_auto_1fr_auto_1fr]">
    <Stat
      size="sm"
      label="Active"
      value="38"
      delta={<Delta value="+4" direction="up" intent="positive" size="sm" />}
      caption="engagements"
    />
    <Separator orientation="vertical" className="hidden h-full sm:block" />
    <Stat
      size="sm"
      label="At risk"
      value="6"
      delta={<Delta value="-2" direction="down" intent="positive" size="sm" />}
      caption="this week"
    />
    <Separator orientation="vertical" className="hidden h-full sm:block" />
    <Stat size="sm" label="Awaiting review" value="11" caption="items" />
  </div>
</Panel>

When to use it

Use it for

Bare KPI figures inside headers, panels, hero metrics, and compact summary strips.
Metrics where the caller already formats currency, percent, points, or locale-specific numbers.
Delta composition when trend meaning needs the full Delta API.

Reach for something else

A bordered KPI tile with sparkline and footer — use StatCard instead.
A row of comparable records — use DataTable instead.
Long explanatory copy or article figures — use Text instead.

Props

Prop	Type	Default	Description
label	ReactNode	—	Eyebrow above the value — the metric's name.
value	ReactNode	—	The metric itself, pre-formatted by the caller ("$2.4M", "94.2%"). A node, not a number — the consumer owns formatting/locale.
delta	ReactNode	—	Trend slot — drop in a <Delta>. A composition slot, not a config, so Delta's full API stays available.
caption	ReactNode	—	Quiet sub-line beside the delta — the comparison basis.
size	"sm" \| "md" \| "lg"	"md"	Visual size of the value.
align	"start" \| "center" \| "end" \| "stretch"	"start"	Cross-axis alignment of the stacked parts.