/// Cards

StatCard

A KPI tile — mono uppercase label, big tabular value, optional unit, delta, and sparkline on a bordered surface. Also exported as KpiStat.

import { StatCard, KpiStat } from "@protocore/pds";

View as Markdown

Basics

A label (mono, uppercase, muted) over a big tabular value, with an optional trailing unit and a muted footer line for context.

p99 latency

184ms

With delta & sparkline

Slot a <MetricDelta> into delta for the change indicator and a <Sparkline> into sparkline for the trend. An icon sits in the label row. The sparkline's signal dot is the single accent point.

Throughput

1,284msg/s+4.2%

KPI row

StatCards tile into a dashboard KPI row. Keep the value formatting consistent (units, precision) across the row.

Uptime

99.99%+0.01%

Active nodes

64+2

Error rate

0.02%-0.4%

Secured

$12B+

When to use it

Use StatCard for a *single* metric that needs a bordered container — a dashboard KPI with a label, a delta, and maybe a trend line. It's imported as KpiStat too, for admin-console code that prefers that name. For a *row of headline figures with no border* (the marketing metrics band), use StatStrip. For just the *change number* on its own, use MetricDelta; for just the *trend line*, use Sparkline. StatCard is the composed tile that hosts those primitives.

Usage

Keep the `label` short and consistent-case — it renders mono uppercase by contract.
Put the number in `value` and the unit in `unit` so the tabular figure stays clean and alignable.
Compose `delta` from `<MetricDelta>` and `sparkline` from `<Sparkline>` rather than hand-rolling markup.
Align precision and units across a KPI row so the numbers compare at a glance.

Don't

Don't bake the unit into the `value` string — you lose the tabular alignment the separate `unit` slot gives.
Don't put more than one trend line in a card; StatCard shows one metric.
Don't use StatCard for a borderless marketing figure band — that's StatStrip.
Don't color the value manually to signal direction; that's what the `delta` slot's MetricDelta does.

Accessibility

StatCard is a static `<div>`; the `icon` in the label row is `aria-hidden` — its meaning is carried by the visible `label` text.
A `<MetricDelta>` conveys direction with a glyph (▲/▼/—) plus the signed number, not color alone, so the trend survives for color-blind users.
Give the `<Sparkline>` an `ariaLabel` when the trend itself is informative; otherwise it stays hidden as decoration.

`StatCard` props

Prop	Type	Default	Description
`className`	`string`	—
`delta`	`ReactNode`	—	Optional metric-delta slot, rendered beside the value (e.g. a MetricDelta).
`footer`	`ReactNode`	—	Optional muted footer line (context, timestamp…).
`icon`	`ReactNode`	—	Optional leading icon slot in the label row.
`label` *	`ReactNode`	—	Metric label — rendered mono, UPPERCASE, muted.
`sparkline`	`ReactNode`	—	Optional sparkline slot beneath the value row.
`style`	`CSSProperties`	—
`unit`	`ReactNode`	—	Optional trailing unit beside the value (e.g. "ms", "%").
`value` *	`ReactNode`	—	The headline figure — big mono, tabular.

`KpiStat` props

Prop	Type	Default	Description
`className`	`string`	—
`delta`	`ReactNode`	—	Optional metric-delta slot, rendered beside the value (e.g. a MetricDelta).
`footer`	`ReactNode`	—	Optional muted footer line (context, timestamp…).
`icon`	`ReactNode`	—	Optional leading icon slot in the label row.
`label` *	`ReactNode`	—	Metric label — rendered mono, UPPERCASE, muted.
`sparkline`	`ReactNode`	—	Optional sparkline slot beneath the value row.
`style`	`CSSProperties`	—
`unit`	`ReactNode`	—	Optional trailing unit beside the value (e.g. "ms", "%").
`value` *	`ReactNode`	—	The headline figure — big mono, tabular.