# Metric Card

One number with its trend and, per variant, a sparkline, progress, breakdown, comparison, distribution, status, action or AI insight.

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

## Install

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

## Import

```tsx
import { MetricCard, ChartCard, MetricBreakdown, MetricComparison, MetricDistribution, MetricDonut, MetricInsight, MetricLegend, MetricProgress, MetricSparkline, MetricStatus } from "@wunderui/react"
```

## Minimal usage

Then use it:

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

export function Revenue() {
  return (
    <MetricCard
      label="Revenue"
      value="$85,250"
      trend={{ value: "+12.3%" }}
      caption="vs last month"
    />
  )
}
```

Expected result: You see a card with the label Revenue, the figure $85,250 and a green +12.3% chip with vs last month beside it.

## When to use

### Use Metric Card for

- A dashboard number that comes with its change, a chart, a goal or a menu
- A figure that needs the context to be read: the period, the previous value, the target
- Cards in a grid or in a Metric Group, with the same structure in every card

### Use something else

- [KPI](https://wunderui.com/components/kpi) for a plain figure with a delta and no chart, menu or chip
- [Metric Group](https://wunderui.com/components/metric-group) for several cards in one frame, divided by hairlines
- [Number Value](https://wunderui.com/components/number-value) for a headline figure that counts up and shows its change as one unit
- [Trend Chip](https://wunderui.com/components/trend-chip) for only the change, in a table cell or a list row

## Keyboard

The card itself has no keyboard behaviour: it is not a tab stop and has no handlers. The controls inside it do, depending on the props you set.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus through the controls of the card in reading order: the icon button (only with `onIconClick`), the (i) button, the ⋯ button, any button you put in the content and the bar chart. Focus shows as an indigo border with a 2 px ring. |
| `Enter` or `Space` | Presses the focused button: opens the ⋯ menu, calls `onIconClick`, or presses a button of your own. |
| `ArrowDown` or `ArrowUp` | On the ⋯ button, opens the menu. In the menu, moves to the next or previous item. |
| `Home` or `End` | In the menu, moves to View details or Remove. On the bar chart, moves to the first or last bar. |
| `Enter` | In the menu, chooses the focused item: `onMenuSelect` is called with `view`, `customize`, `export` or `remove`, the menu closes and focus returns to the ⋯ button. |
| `Escape` | Closes the menu and returns focus to the ⋯ button, or closes the info tooltip. |
| `ArrowLeft` or `ArrowRight` | On a bar chart, moves to the previous or next bar and announces its name and value, for example `Sat: 870 orders`. ArrowUp and ArrowDown do the same. It stops at the first and last bar, and leaving the chart clears the highlight. |

## Behavior

What the card renders and how it reads.

- **Not pressable:** The card has no focus, hover, selected state or handlers. Put the action in a button inside the card, or wrap the card in your own link.
- **Header:** The icon adds a 32 px tile or icon button, info an (i) with a tooltip, menu the ⋯ menu. The tooltip opens on hover and keyboard focus and closes on Escape, and a long label shortens to make room.
- **Menu:** The menu opens View details, Customize, Export data and Remove (red, below a separator) and reports the chosen action. Pass your own trigger to replace the whole control.
- **Trend:** A trend draws a Trend Chip, up by default. Colour follows direction by default (up green, down red, neutral grey); set sentiment to positive, negative or neutral when the change is good or bad the other way, such as a falling churn (positive) or a rising overdue count (negative). The arrow always follows direction.
- **Layout:** The value and chip stack in one column. With a side element they sit beside it, a chart on the chip's baseline and a ring centred, and the previous line goes below both.
- **Numbers:** Nothing is formatted or rounded. The value wraps only at spaces, so keep it short; a figure without spaces runs past the edge of a narrow card.
- **Charts:** A line or area is a named image with no readout. Bars are a focusable group: hover, press or arrow keys light one bar, show a readout when a formatter is set, and announce it in a live region.
- **Progress:** MetricProgress computes the percentage from value and max, rounds it and shows it as text; a max of 0 or a non-number shows 0%. The ring is an image named with its percentage.
- **Reading order:** A screen reader reads the label, the info and menu buttons, then the value, trend and caption, then the content. Label and value are plain text, so add a heading around a group of cards.
- **States:** There is no loading, empty, error or stale state yet. The Examples tab composes them: a skeleton, a dash with a reason, and a caption saying how old the figure is.
- **Motion:** The card does not animate and the value does not count up. Bars change colour quickly, the menu panel fades and scales in, and the tooltip has its own animation.
- **Reduced motion:** Under reduced motion, moving properties drop out of every transition and colour and opacity stay. Menu and tooltip fade without zooming, and a skeleton stops its shimmer.

## Anatomy

- `MetricCard`: A div with a 1 px border, 16 px radius, card surface, 16 px padding and 16 px between sections. It has no shadow, role or handlers and fills its parent's width, so set a width or use a grid.
- `Icon`: The icon in a 32 px tile with a muted fill, or in a bordered icon button. The button is a tab stop only when you set a click handler; otherwise it is decorative.
- `Label`: The label at 12 px medium in tertiary text, on one line with an ellipsis.
- `Info`: A small (i) button next to the label that shows a tooltip on hover and keyboard focus. It is named About followed by the label.
- `Menu`: The ⋯ button at the end of the header with View details, Customize, Export data and Remove. Pass your own trigger to replace it.
- `Value`: The value at 30 px bold with tabular figures, shown exactly as you pass it. It wraps at spaces, so 780 / 1,000 can take two lines in a narrow card.
- `Trend chip`: A Trend Chip under the value with a glyph and the finished label: green for up, red for down, grey for neutral.
- `Caption`: The caption beside the chip, such as vs last month. Without a trend it stands alone under the value, and the previous line sits below.
- `Visualization`: What the card shows besides the number: under the value as children, or beside it. A chart beside the value stands on the chip's baseline; a ring stays centred.
- `MetricSparkline`: A line, an area or bars. Bars are a focusable group with arrow-key navigation and a live readout; line and area are a named image.
- `MetricProgress`: A linear bar, a segmented bar or a ring, with the percentage computed from value and max.
- `MetricBreakdown`: A description list of label and figure rows under a hairline.
- `MetricComparison`: Two or more periods as horizontal bars with their figures. The first bar is solid, the rest are pale.
- `MetricDistribution`: A stacked bar of parts with a legend under it, named after its parts and percentages.
- `MetricDonut`: The ring of the same parts, placed beside the value. Put a MetricLegend in the body.
- `MetricLegend`: The dots-and-labels list of a distribution, with each part's percentage.
- `MetricStatus`: A light pill Badge with a short note beside it.
- `MetricInsight`: A sentence on the indigo tint with an icon, a bolt by default.
- `ChartCard`
- `Header`
- `Value`
- `Content`
- `Metric Sparkbars`

## Best practices

### Do

- Pass finished strings in English format: $85,250, 12.3%, 1.2M. The card formats nothing, and the trend takes its label with the sign: +12.3%, -3.1%.
- Name the comparison. Put what the change is measured against in the caption (vs last month) and, where it helps, the previous value.
- Choose one visualization per card. A sparkline, a goal or a breakdown each answers one question; two together are hard to read.
- Name your charts. The label on a sparkline and the labels on bars are what a screen reader hears; the default, Trend, says nothing about the figure.
- Put an action in a button inside the card and name it. The card itself is not pressable.
- Swap the card for a skeleton of the same size while loading, and keep it with a note when the figure is old. The card has no loading, empty or error state.
- Inside a dashboard cell or a row of equal cards, pass fill: the card takes the full height and keeps its visualization on the bottom edge.

### Don't

- Don't leave the colour to the direction when the change is good or bad the other way round. Set trend.sentiment: a falling churn is positive (green), a rising overdue count negative (red).
- Don't rely on the chart for exact numbers. Lines and areas have no readout and bars show values on hover and focus, so put the number in the card as text.
- Don't pass parts that do not add up. Breakdown, Distribution and Donut draw what you give them and do not check the sum.
- Don't use it for a figure without a trend, chart or menu. KPI is the lighter card for that.

## API reference

### MetricCard

| Prop | Type | Default | Description |
|---|---|---|---|
| label* | string |  | What the figure is, for example `Revenue`. Required. It also names the (i) and ⋯ buttons. It stays on one line with an ellipsis. |
| value* | string |  | The figure as a finished string, for example `$85,250`. Required. It is not formatted and wraps only at spaces. |
| aside | ReactNode |  | Sits beside the value: a ring, a donut or a chart. |
| asideAlign | "center" \| "end" |  | `end` puts the aside on the baseline of the chip, `center` centres it. Defaults to `end` for a MetricSparkline and `center` for anything else. |
| caption | ReactNode |  | Beside the chip, for example `vs last month`. Without a trend it stands alone under the value. |
| children | ReactNode |  | The visualization or content under the value: MetricSparkline, MetricProgress, a button, an avatar group. |
| className | string |  | Extra classes for the root, for example a width. The card is full width by default. |
| fill | boolean | false | Fills the height of its container (a dashboard grid cell): the card takes `h-full`, the content area grows and keeps its visualization on the bottom edge; a chart from `@wunderui/react/charts` in it takes the free height. |
| icon | ReactNode |  | A glyph for the tile or the icon button, for example a Lucide icon. |
| iconColor | "indigo" \| "blue" \| "purple" \| "pink" \| "red" \| "orange" \| "yellow" \| "green" \| "alternative" |  | Tile colour: a plain tint surface with the icon in the same hue (the Figma Icon tile set). Without it the tile is muted. |
| iconVariant | "tile" \| "button" | "tile" | A muted 32 px tile or a bordered icon button. Defaults to `tile`. |
| info | ReactNode |  | The text of the tooltip behind the (i) next to the label. Without it there is no (i). |
| menu | boolean \| ReactNode |  | `true` for the ⋯ menu with View details, Customize, Export data and Remove, or your own trigger to replace it. |
| onIconClick | () => void |  | Makes the icon button do something. With it the button is a tab stop named after the label; without it the button is decorative and hidden from assistive technology. |
| onMenuSelect | (action: "view" \| "customize" \| "export" \| "remove") => void |  | Called with the chosen entry of the built-in menu. |
| previous | ReactNode |  | The previous value as a line under the chip and the caption, for example `Previous period $75,900`. |
| trend | { value: string; direction?: "up" \| "down" \| "neutral"; icon?: TrendChipIcon } |  | The Trend Chip under the value. `value` is the finished label with its sign. `direction` defaults to `up`. `icon` picks the glyph, as on Trend Chip. |

### ChartCard

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | ReactNode |  |  |
| title* | ReactNode |  |  |
| action | ReactNode |  |  |
| className | string |  |  |
| delta | { value: ReactNode; direction?: "up" \| "down"; good?: boolean; caption?: ReactNode } |  | Trend chip under the value: "18.2%" with an arrow; `good` decides the colour (defaults to up = good). |
| description | string |  |  |
| hiddenSeries | string[] |  | Series labels switched off. Their legend chips stay, dimmed, so they can be switched back on. |
| legend | { label: string; color?: string; badge?: BadgeColor }[] |  | Legend chips under the header: a dot in the series colour (token or hex) on the muted surface. `badge` is kept for compatibility and no longer used. |
| onLegendToggle | (label: string) => void |  | Makes the legend chips toggle buttons (`aria-pressed`): called with the chip label. Hide the series in the chart yourself, e.g. by dropping it from `categories`. |
| onPeriodChange | (period: string) => void |  |  |
| period | string |  |  |
| periods | string[] |  | The period segment, top right. |
| value | ReactNode |  | The headline number under the title, e.g. "$84,250" — the title then reads as its small label. |

### MetricBreakdown

| Prop | Type | Default | Description |
|---|---|---|---|
| rows* | { label: string; value: string }[] |  | The rows. Required. The values are finished strings; they are not summed. |
| className | string |  | Extra classes for the list. |

### MetricComparison

| Prop | Type | Default | Description |
|---|---|---|---|
| series* | { label: string; value: string; percent: number }[] |  | The periods. Required. `percent` is the length of the bar from 0 to 100; the first row is solid and the others are pale. |
| className | string |  | Extra classes for the wrapper. |

### MetricDistribution

| Prop | Type | Default | Description |
|---|---|---|---|
| parts* | { label: string; percent: number; color?: string }[] |  | The parts. Required. `percent` is the width of the segment, `color` any CSS colour. The percentages are not checked against 100. |
| className | string |  | Extra classes for the wrapper. |

### MetricDonut

| Prop | Type | Default | Description |
|---|---|---|---|
| parts* | { label: string; percent: number; color?: string }[] |  | The parts of the ring, as for MetricDistribution. Required. |
| className | string |  | Extra classes for the ring. |

### MetricInsight

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | ReactNode |  | The sentence. Required. |
| className | string |  | Extra classes for the box. |
| icon | ReactNode |  | Replaces the bolt. |

### MetricLegend

| Prop | Type | Default | Description |
|---|---|---|---|
| parts* | { label: string; percent: number; color?: string }[] |  | The parts to list, with their percentages. Required. |
| className | string |  | Extra classes for the list. |

### MetricProgress

| Prop | Type | Default | Description |
|---|---|---|---|
| value* | number |  | The current value. Required. |
| className | string |  | Extra classes for the wrapper. |
| label | ReactNode |  | The text under the bar, on the left, for example `$72,000 of $100,000 target`. A string also names the bar for assistive technology. |
| max | number | 100 | The value that counts as 100%. Defaults to 100. |
| segments | number | 5 | The number of segments of the segmented style. Defaults to 5. |
| variant | "linear" \| "segmented" \| "radial" | "linear" | A bar, a bar of segments or a ring for `aside`. Defaults to `linear`. |

### MetricSparkline

| Prop | Type | Default | Description |
|---|---|---|---|
| data* | number[] |  | The series. Required. A single value draws a flat line; an empty array draws an empty image. |
| className | string |  | Extra classes, for example a width when the chart sits in `aside`. |
| color | "primary" \| "green" | "primary" | The brand indigo or a green tint. Defaults to `primary`. |
| formatValue | (value: number) => string |  | Bars only: formats a bar's value. With it, the bar under the pointer or focus shows a small readout above the bars. |
| height | number | 40 | Height in px. Defaults to 40. |
| highlight | number |  | Bars only: the index drawn solid at rest. Defaults to the last bar. |
| label | string | "Trend" | The accessible name of the chart. Defaults to `Trend`; name the figure instead, for example `Orders per day`. |
| labels | string[] |  | Bars only: a name per bar, such as `Mon`, used in the readout and the announcement. |
| variant | "line" \| "area" \| "bar" | "line" | A line, an area with a soft fill or mini bars. Defaults to `line`. |

### MetricStatus

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | ReactNode |  | The text of the pill, for example `Healthy`. Required. |
| caption | ReactNode |  | A short note beside the pill, for example `All systems operational`. |
| className | string |  | Extra classes for the wrapper. |
| color | BadgeColor | "green" | The colour of the Badge, as on Badge. Defaults to `green`. |

## Examples

### Header: label, icon, icon button, info or menu

### Trend: none, up, down, flat or with the previous period

### Chart: line, area or bars, under the value or beside it

### Goal: progress as a bar, segments or a ring

### Parts: a total as rows, a comparison, segments or a donut

### Content: status, action, insight or people

## In context

### Overview: one card for the period you choose

The value, change, previous period and series shape change together. The chart shows the shape and the chip carries the number.

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

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

### Plan usage: a goal, an icon button and a report link

Press the icon button or the link: each reports below what it opened. The card is not a link, so the actions are buttons inside it.

### Report cards: the chart under the value or beside it

Two cards side by side. The first puts the chart under the value with a link; the second puts a smaller one beside it.

## For AI agents

`get_component("metric-card")`

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