# Metric card

A React component in [Beamline](https://beamline.io/)'s [Dashboard](https://beamline.io/components/dashboard) category. Live demo: https://beamline.io/components/metric-card

A KPI: label, a value that rolls to each new number, the change with arrow, sign and tone, a trend line and context; unmeasured values are hatched, never zero.

## Use it for

- Headline numbers on dashboards.

## Not for

- A number inside a sentence ([slot-text](https://beamline.io/components/slot-text)).
- Several related numbers (a [table](https://beamline.io/components/table) or bar list).

## Anatomy

- root (m-surface card; bezel frame: shell + inset panel)
- label
- value (slot text, LTR-isolated figures)
- change line: delta badge (▲/▼/■, sign, unit) + comparison (deltaLabel), read as one phrase
- trend line
- context (pinned to the bottom so cards in a row align)

## Variants

- **frame**: plain, bezel

## States

- up good
- up bad (invert)
- flat
- not measured (hatched swatch + “Not measured”, no badge)
- percentage points (pp)
- loading (`loading`: the label, value line, change row, trend and context hold their real heights with placeholders; a row is held when its prop is given, an empty label holds the label's line)

## Keyboard

- Not interactive

## Motion

The value rolls to new numbers (SlotText). Nothing else moves; the badge and comparison swap instantly.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — |  |
| `value / format` | `number \| null / (v) => string` | — |  |
| `delta / deltaLabel / invert` | `number / string / boolean` | — |  |
| `trend` | `(number \| null)[]` | — |  |
| `context` | `ReactNode` | — |  |
| `frame` | `"plain" \| "bezel"` | — |  |
| `deltaUnit / deltaFormat` | `"fraction" \| "percentage-points" / (delta: number, unit: MetricDeltaUnit) => string` | — | Fraction preserves the existing relative percentage API. Percentage-points uses an already calculated point change: -9 reads −9 pp and down 9 percentage points. A custom display formatter does not replace the accessible unit. |
| `style / ref` | `CSSProperties / native Ref` | — |  |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | — | The plain frame label is a heading: its level (default 3); 2 for KPIs directly under a page title. |
| `classNames` | `MetricCardClassNames` | — |  |
| `trendClassNames` | `TrendLineClassNames` | — |  |
| `loading` | `boolean` | `false` | value, change, trend and context held at their real heights while the number loads; a row is held when its prop is given |

## Import

```tsx
import { MetricCard } from "@/components/metric-card/metric-card";
```

## Get it

Metric card is part of Beamline: 190 React components and screens your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 one payment (regular $200), no subscription, a year of updates, one licence for your whole team. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in Dashboard

- [App shell](https://beamline.io/components/app-shell): The frame for every app screen: collapsible sidebar with grouped navigation, top bar and page.
- [Bar list](https://beamline.io/components/bar-list): Ranked horizontal bars with label inside and value at the end — top pages, sources, customers.
- [Category bar](https://beamline.io/components/category-bar): One bar split into labelled ranges with an optional marker that names its range.
- [Insight cards](https://beamline.io/components/insight-cards): Findings from an agent, one per page: the sentence, the series it is about with their change, a chart to scrub that names each point, and a follow-up…
- [Tracker](https://beamline.io/components/tracker): A row of status blocks for uptime, job runs or daily checks, with tooltips and a legend.