# KPI

A single metric with its change, as a card with a dot and delta, a plain card with a caption, or an inline value.

- Category: KPI / Metric Card
- Page: https://wunderui.com/components/kpi
- Tier: Core and Pro

## Install

KPI ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { StatCard } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { StatCard } from "@wunderui/react"

export function Revenue() {
  return <StatCard label="Revenue" value="$48,200" delta="+12.4%" trend="up" />
}
```

Expected result: You see a card with a dot at the top left, a green +12.4% with an arrow at the top right, the label Revenue and the figure $48,200.

## When to use

### Use KPI for

- A single figure with its label on a dashboard, a report header or a settings page
- A figure with a change since a reference, where an arrow and a colour are enough
- A bare figure in a page header, with the inline style

### Use something else

- [KPI Group](https://wunderui.com/components/kpi-group) for several figures in one frame, divided by hairlines
- [Metric Card](https://wunderui.com/components/metric-card) for a figure with a trend chip, a sparkline, progress or a menu
- [Number Value](https://wunderui.com/components/number-value) for a headline figure that counts up and shows its change as one unit

## Behavior

What the card renders and how it reads.

- **Static:** StatCard is not interactive: no focus, no hover state, no handlers, no role. Wrap it in your own link or button where the figure should open something.
- **Three styles:** Trend (default) draws dot, delta, label, value and previous value; simple draws label, value and caption; inline draws value over label with no frame. Props a style doesn't draw are ignored.
- **Colour follows trendGood:** Good trends are green, bad ones red, and the arrow always follows the trend, so falling churn points down in green. With no delta the top row is shorter and the label sits 8 px higher.
- **Numbers:** Nothing is formatted or rounded. Simple and inline use tabular figures; trend doesn't, so a column of changing figures can shift by a pixel.
- **Size:** The card fills its parent's width and takes the height of its content. Give it a width with a class or put it in a grid, where cards of a row stretch to the same height.
- **Long content:** A long label wraps onto more lines and the card grows. The value wraps only at spaces, so a figure without spaces that is wider than the card runs past its edge; keep it short or compact it.
- **Reading order:** In the trend style a screen reader reads the change, then the label, then the value; in simple it reads label then value, and in inline the value first. The arrow is hidden.
- **States:** There is no loading, empty, error or stale state. The Examples tab composes each around the card: a skeleton, a dash with a reason, and a caption saying how old the figure is.
- **Motion:** None. The figure and delta appear as they are and don't animate when they change.
- **Reduced motion:** There is no motion, so reduced motion changes nothing.

## Anatomy

- `StatCard`: A div with a 1 px border, a 16 px radius, a card surface and 16 px padding. It has no shadow and no role, and fills the width of its flex or grid parent; the variant picks the layout.
- `Dot`: An 8 px dot at the top left of the trend style, in the brand colour by default. It is decorative and carries no text.
- `Delta`: The change text at the top right of the trend style, followed by an arrow. The arrow follows the trend and the colour follows whether that trend is good; it shows only when a delta is set.
- `Label`: The label under the top row: 13 px in the trend style, 12 px in simple and inline. It wraps onto more lines when long.
- `Value`: The value as a bold 24 px paragraph (16 px semibold inline), shown exactly as you pass it. It wraps at spaces, so a figure without spaces runs past the card edge; there is no ellipsis.
- `Previous`: A 12 px line under the value of the trend style: Prev: followed by the previous value. The simple style shows a caption in the same place.

## Best practices

### Do

- Pass finished strings in the English format: $1,842.50, 12.4%, 1.2M. The card formats nothing, so value and delta appear exactly as written.
- Put the sign in the delta (+12.4%, -3.1%). The arrow is hidden from screen readers, so the sign is the only direction they get.
- Mark every metric where a fall is good or a rise is bad, such as churn, error rate or open tickets. The arrow follows the trend, the colour follows whether it is good.
- Compact long figures before you pass them (1.2M instead of 1,234,567). A figure without spaces doesn't wrap, so in a narrow card a long one runs past the edge.
- Replace the card with a skeleton of the same size while it loads, and keep the card with a note when the figure is old. The card has no loading, empty or error state of its own.

### Don't

- Don't skip the good-trend setting and rely on the arrow for a metric where up is bad. A rising ticket count in green reads as good news.
- Don't use the trend style when you need a chip, a chart or a menu. Use Metric Card, which has all three.
- Don't put a pressable action on the card itself. It has no focus state or handlers; wrap it in your own link or button if the figure should open a report.
- Don't set delta, previous or dot colour on the simple or inline style. Those styles don't draw them.

## API reference

### StatCard

| Prop | Type | Default | Description |
|---|---|---|---|
| label* | string |  | What the figure is, for example `Revenue`. Required. It wraps when it is long. |
| value* | string |  | The figure as a finished string, for example `$1,842.50`, `12.4%` or `1.2M`. Required. It is not formatted, and a figure without spaces does not wrap. |
| caption | ReactNode |  | A line under the value, for example `4 new this month`. `simple` style only; it can hold more than text, so a state message with a retry button fits. |
| className | string |  | Extra classes for the root, for example a width. The inline style has no frame, so a width there only sizes the text. |
| delta | string |  | The change, as a finished string with its sign, for example `+12.4%`. Shown by the `trend` style only, with an arrow. Without it the top row shows the dot alone. |
| dotColor | string | "var(--primary)" | Any CSS colour for the dot, for example `var(--tint-text-green)`. Defaults to `var(--primary)`. `trend` style only. |
| prev | string |  | The previous value, shown under the figure as `Prev: ` followed by this string. `trend` style only. |
| trend | "up" \| "down" | "up" | Which way the arrow points. Defaults to `up`. There is no neutral value: leave out `delta` instead. |
| trendGood | boolean | true | Whether the change is good, which sets the colour of the delta and its arrow: green for true, red for false. Defaults to true. |
| variant | "trend" \| "simple" \| "inline" | "trend" | The layout. `trend` draws the dot, the delta and the previous value, `simple` draws a caption under the value, `inline` draws the bare value over the label with no frame. Defaults to `trend`. |

## Examples

### Style: trend, simple or inline

### Change: which way it moved and whether that is good

### Number format: currency, percent, compact or count

### Content: previous value, long label, long value

## In context

### Overview: four figures for the period you choose

Four separate cards in your own grid. A fall in open tickets is good and stays green; a fall in conversion is bad and turns red.

### States: ready, loading, empty, error, stale

The card has no states of its own. Show a skeleton while loading, a dash with a reason when empty or failed, and keep a stale figure with its age.

### Inline: figures in a page header

The inline style has no frame, so three figures sit under a title without turning into three boxes.

## For AI agents

`get_component("kpi")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
