import { MetricCard } from "@elabs-ai/components-ui";npm install @elabs-ai/components-tokens @elabs-ai/components-uiPaste it into Claude Code, Cursor, Codex or any other coding agent. Text in [brackets] is yours to fill in.
Add the brand-ui MetricCard component (from @elabs-ai/components-ui) to this project. 1. Read https://elabs-ai.com/llms.txt first: it maps every package and the rules. If you can use MCP servers, connect https://elabs-ai.com/mcp and use its search, docs and tokens tools. If not, run the same lookups in the terminal: `npx -y @elabs-ai/components-cli search "<what you need>"` and `npx -y @elabs-ai/components-cli docs <Component>`. 2. Look MetricCard up before writing code: `npx -y @elabs-ai/components-cli docs MetricCard` prints its real props, variants, what it pairs with and what to avoid. 3. If @elabs-ai/components-ui is not installed yet: `pnpm add @elabs-ai/components-tokens @elabs-ai/components-ui` (or `npm install @elabs-ai/components-tokens @elabs-ai/components-ui`). If this is the first brand-ui package in the project, wire it once: import `@elabs-ai/components-tokens/styles.css` plus the `themes/light.css` and `themes/dark.css` stylesheets in the CSS entry, add one Tailwind `@source` line per installed @elabs-ai package (Tailwind does not scan node_modules, so without it everything renders unstyled), and wrap the app root in `ThemeProvider` from `@elabs-ai/components-tokens`. 4. Use it here: [the screen or file, and what it should show] 5. Rules: use only @elabs-ai/components-* components and the semantic tokens — no raw colours, no raw font sizes, no arbitrary Tailwind values. Look up each component's real props with the docs tool before you use it; never guess a prop. 6. Done means: the typecheck passes, `npx -y @elabs-ai/components-cli audit src --strict` reports nothing, and you have opened the app and looked at every screen you touched in the light and the dark theme.
Avoid
- Numbers without tabular-nums — figures jitter across a row; use tabular-nums for any number column.
- Encoding up/down by color alone — pair with an arrow/sign.
- Re-declaring a KPI tile in another package — MetricCard is owned by @elabs-ai/components-ui; charts and editor re-export it (ADR 0012).
Works with
Used inside
Examples
With Description
Delta Down
Delta Unfavorable
Comparisons
Several named changes side by side: the `comparisons` row puts month over month beside year over year (or actual vs target vs last year) as chips under the tile body. Each chip carries an arrow, the sign and a tone, and a bad-news chip also differs in shape — a dashed outline — so the row still reads in greyscale. `delta` stays the one headline change beside the value.
Neutral
No Metrics
Headline
With Evidence
Numeric Value
A NUMERIC `value` is compacted for reading and stays reachable in full: the tile renders its value as a real button that copies the exact figure. The accessible name carries the tile's own label, so two tiles that compact to the same string are still told apart by a screen reader.
Numeric Uncompacted
`valueFormat="number"` is the escape hatch — full grouped digits, no copy control.
Numeric Currency
Currency and percent read the same numeric seam.
Loading
Loading vs ready (#268) — a layout-shaped skeleton at the same box height as `Default`.
Size Small
`size="sm"` — label + value only, for the smallest sheet tiles (RM-072).
With Sparkline Slot
The `sparkline` slot sits directly under the value (RM-072).
Size Large
`size="lg"` — the kpi value rung with room for the trend slot (RM-072).
API
MetricCard
| Prop | Type | Description |
|---|---|---|
labelrequired | ReactNode | |
valuerequired | ReactNode | |
valueFormat | MetricCardValueFormat | How to render a NUMERIC `value`. Default: `"compact"`. Ignored for every other `ReactNode` — a string you already formatted is rendered verbatim. |
currency | string | ISO 4217 code for `valueFormat: "currency"`. Default: `"USD"`. |
copyExactValue | boolean | Offer the exact figure on click when a numeric `value` was shortened. Default: `true`. Turning it off leaves a compacted number with no way back to its digits, so only do that when the tile is decorative. |
description | ReactNode | Secondary line under the value — sublabel / context. |
delta | string | Signed change, e.g. "+12.4%". Direction colors it. |
deltaDirection | "up" | "down" | "neutral" | |
positiveIsGood | boolean | Whether "up" is good (green) — flip for metrics where down is good. |
comparisons | MetricCardComparison[] | Several named changes side by side, as a row of chips under the tile body — month over month beside year over year, or actual against target and against last year. Each chip carries an arrow, the sign and a tone, and a bad-news chip also differs in SHAPE (a dashed outline), so the row survives greyscale. Use `delta` for the ONE headline change beside the value and this for the rest; hidden at `size="sm"`. Default: none. |
icon | ReactNode | |
visual | ReactNode | Optional inline visual shown under the value/description. |
sparkline | ReactNode | Trend slot rendered directly under the value (RM-072) — pass a `<Sparkline …/>` from `@elabs-ai/components-charts`. Hidden at `size="sm"`. |
evidence | ReactNode | Optional grounding footer (research 11 §B.5 KPI-3) — connects a cited figure to its source (e.g. an `EvidenceChip` from `@elabs-ai/components-ai`). Rendered subdued (`text-meta text-muted-foreground`) under the tile body. |
loading | boolean | Loading vs ready — renders a layout-shaped skeleton (matching the real box height) instead of the value/label/delta text. Default: `false`. |
announceLoading | boolean | Whether this tile announces its own `loading` state via a live region. Set to `false` when several tiles are composed inside a container that already announces once for the whole region (e.g. a loading `MetricGrid`) — see loading-states.md §a11y ("one live region per region, not per box"). Default: `true`. |
Theming
The tokens each state resolves to. Change the token and every theme follows.
| State | Token |
|---|---|
| value | tabular-nums |