Skip to content
WunderUI

Metric Card

Pro

One number with its label and trend, and optionally under it a sparkline, progress bar, breakdown, status, action or insight.

Playground

Revenue
$85,250
+12.3%vs last month

Installation

Metric Card comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

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

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 for

  • KPI for a plain figure with a delta and no chart, menu or chip
  • Metric Group for several cards in one frame, divided by hairlines
  • Number Value for a headline figure that counts up and shows its change as one unit
  • Trend Chip for only the change, in a table cell or a list row

The header sits above the value with an optional icon, an info tooltip by the label, and a menu (View details, Customize, Export data, Remove). A long label ends in an ellipsis.

Revenue
$85,250
+12.3%vs last month

Trend

The trend chip is green up, red down or grey neutral, with a caption and the previous value. Colour follows direction only, so a good fall like churn still shows red.

Revenue
$85,250

Chart

A sparkline goes under the value or beside it. Lines and areas fill the card width; bars take labels for a readout and move with the arrow keys.

Revenue
$85,250
+12.3%vs last month

Goal

MetricProgress shows how far a figure has come, computed from value and max. The radial style is a ring beside the value; linear and segmented go under it.

Revenue
$72,000
+12.3%
x
$72,000 of $100,000 target72%

Parts

Show a total split into rows, compared with the last period, or shared out as stacked segments or a ring. The parts are your numbers: the card does not check they add up.

Revenue
$85,250
+12.3%
Enterprise
$41,200
Growth
$24,800
Starter
$12,650
Add-ons
$6,600

Content

Anything else goes in as children: a status badge, a button, an insight sentence, an avatar group. The card is not pressable, so an action is a button inside it.

Uptime
99.98%
HealthyAll systems operational

Keyboard interactions

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.

TaborShiftTab
Moves focus through the controls of the card in reading order: the icon button (only with ), 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.
EnterorSpace
Presses the focused button: opens the ⋯ menu, calls , or presses a button of your own.
ArrowDownorArrowUp
On the ⋯ button, opens the menu. In the menu, moves to the next or previous item.
HomeorEnd
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: is called with , , or , the menu closes and focus returns to the ⋯ button.
Escape
Closes the menu and returns focus to the ⋯ button, or closes the info tooltip.
ArrowLeftorArrowRight
On a bar chart, moves to the previous or next bar and announces its name and value, for example . ArrowUp and ArrowDown do the same. It stops at the first and last bar, and leaving the chart clears the highlight.

Behavior and motion

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

The figure shows a card with every header part, the trend and a chart beside the value. The visualization parts below go in as children or beside the value.

Revenue
$85,250
+12.3%vs last month
  • data-slot="metric-card"

    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.

  • Optional

    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.

  • The label at 12 px medium in tertiary text, on one line with an ellipsis.

  • Optional

    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.

  • Optional

    The ⋯ button at the end of the header with View details, Customize, Export data and Remove. Pass your own trigger to replace it.

  • 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.

  • Optional

    A Trend Chip under the value with a glyph and the finished label: green for up, red for down, grey for neutral.

  • Optional

    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.

  • Optional

    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.

  • Optional

    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.

  • Optional

    A linear bar, a segmented bar or a ring, with the percentage computed from value and max.

  • Optional

    A description list of label and figure rows under a hairline.

  • Optional

    Two or more periods as horizontal bars with their figures. The first bar is solid, the rest are pale.

  • Optional

    A stacked bar of parts with a legend under it, named after its parts and percentages.

  • Optional

    The ring of the same parts, placed beside the value. Put a MetricLegend in the body.

  • Optional

    The dots-and-labels list of a distribution, with each part's percentage.

  • Optional

    A light pill Badge with a short note beside it.

  • Optional

    A sentence on the indigo tint with an icon, a bolt by default.

  • data-slot="metric-card-header"
  • data-slot="metric-card-value"
  • data-slot="metric-card-content"Optional
  • data-slot="metric-sparkbars"
  • data-slot="chart-card"Optional

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%.

  • Do

    Name the comparison. Put what the change is measured against in the caption (vs last month) and, where it helps, the previous value.

  • Do

    Choose one visualization per card. A sparkline, a goal or a breakdown each answers one question; two together are hard to read.

  • Do

    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.

  • Do

    Put an action in a button inside the card and name it. The card itself is not pressable.

  • Do

    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.

  • 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

    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

    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

    Don't use it for a figure without a trend, chart or menu. KPI is the lighter card for that.

  • Do

    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.

API reference

One table per part. MetricCard and its parts are plain components, so these tables list every prop, and the trend object has a value plus an optional direction, icon and sentiment.

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.

PropTypeDefaultDescription
label requiredstring—What the figure is, for example . Required. It also names the (i) and ⋯ buttons. It stays on one line with an ellipsis.
value requiredstring—The figure as a finished string, for example . Required. It is not formatted and wraps only at spaces.
iconReactNode—A glyph for the tile or the icon button, for example a Lucide icon.
iconVariant"tile" | "button""tile"A muted 32 px tile or a bordered icon button. Defaults to .
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.
infoReactNode—The text of the tooltip behind the (i) next to the label. Without it there is no (i).
menuboolean | ReactNode— for the ⋯ menu with View details, Customize, Export data and Remove, or your own trigger to replace it.
onMenuSelect(action: "view" | "customize" | "export" | "remove") => void—Called with the chosen entry of the built-in menu.
trend{ value: string; direction?: "up" | "down" | "neutral"; icon?: TrendChipIcon }—The Trend Chip under the value. is the finished label with its sign. defaults to . picks the glyph, as on Trend Chip.
captionReactNode—Beside the chip, for example . Without a trend it stands alone under the value.
previousReactNode—The previous value as a line under the chip and the caption, for example .
asideReactNode—Sits beside the value: a ring, a donut or a chart.
asideAlign"center" | "end"— puts the aside on the baseline of the chip, centres it. Defaults to for a MetricSparkline and for anything else.
childrenReactNode—The visualization or content under the value: MetricSparkline, MetricProgress, a button, an avatar group.
classNamestring—Extra classes for the root, for example a width. The card is full width by default.
fillbooleanfalseFills the height of its container (a dashboard grid cell): the card takes , the content area grows and keeps its visualization on the bottom edge; a chart from in it takes the free height.
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.

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.

PropTypeDefaultDescription
data requirednumber[]—The series. Required. A single value draws a flat line; an empty array draws an empty image.
variant"line" | "area" | "bar""line"A line, an area with a soft fill or mini bars. Defaults to .
heightnumber40Height in px. Defaults to 40.
color"primary" | "green""primary"The brand indigo or a green tint. Defaults to .
highlightnumber—Bars only: the index drawn solid at rest. Defaults to the last bar.
labelstring"Trend"The accessible name of the chart. Defaults to ; name the figure instead, for example .
labelsstring[]—Bars only: a name per bar, such as , used in the readout and the announcement.
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.
classNamestring—Extra classes, for example a width when the chart sits in .

A linear bar, a segmented bar or a ring, with the percentage computed from value and max.

PropTypeDefaultDescription
value requirednumber—The current value. Required.
maxnumber100The value that counts as 100%. Defaults to 100.
labelReactNode—The text under the bar, on the left, for example . A string also names the bar for assistive technology.
variant"linear" | "segmented" | "radial""linear"A bar, a bar of segments or a ring for . Defaults to .
segmentsnumber5The number of segments of the segmented style. Defaults to 5.
classNamestring—Extra classes for the wrapper.

A description list of label and figure rows under a hairline.

PropTypeDefaultDescription
rows required{ label: string; value: string }[]—The rows. Required. The values are finished strings; they are not summed.
classNamestring—Extra classes for the list.

Two or more periods as horizontal bars with their figures. The first bar is solid, the rest are pale.

PropTypeDefaultDescription
series required{ label: string; value: string; percent: number }[]—The periods. Required. is the length of the bar from 0 to 100; the first row is solid and the others are pale.
classNamestring—Extra classes for the wrapper.

A stacked bar of parts with a legend under it, named after its parts and percentages.

PropTypeDefaultDescription
parts required{ label: string; percent: number; color?: string }[]—The parts. Required. is the width of the segment, any CSS colour. The percentages are not checked against 100.
classNamestring—Extra classes for the wrapper.

The ring of the same parts, placed beside the value. Put a MetricLegend in the body.

PropTypeDefaultDescription
parts required{ label: string; percent: number; color?: string }[]—The parts of the ring, as for MetricDistribution. Required.
classNamestring—Extra classes for the ring.

The dots-and-labels list of a distribution, with each part's percentage.

PropTypeDefaultDescription
parts required{ label: string; percent: number; color?: string }[]—The parts to list, with their percentages. Required.
classNamestring—Extra classes for the list.

A light pill Badge with a short note beside it.

PropTypeDefaultDescription
colorBadgeColor"green"The colour of the Badge, as on Badge. Defaults to .
children requiredReactNode—The text of the pill, for example . Required.
captionReactNode—A short note beside the pill, for example .
classNamestring—Extra classes for the wrapper.

A sentence on the indigo tint with an icon, a bolt by default.

PropTypeDefaultDescription
children requiredReactNode—The sentence. Required.
iconReactNode—Replaces the bolt.
classNamestring—Extra classes for the box.

PropTypeDefaultDescription
children requiredReactNode—
title requiredReactNode—
actionReactNode—
delta{ value: ReactNode; direction?: "up" | "down"; good?: boolean; caption?: ReactNode }—Trend chip under the value: "18.2%" with an arrow; decides the colour (defaults to up = good).
descriptionstring—
hiddenSeriesstring[]—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. is kept for compatibility and no longer used.
onLegendToggle(label) => void—Makes the legend chips toggle buttons (): called with the chip label. Hide the series in the chart yourself, e.g. by dropping it from .
onPeriodChange(period) => void—
periodstring—
periodsstring[]—The period segment, top right.
valueReactNode—The headline number under the title, e.g. "$84,250" — the title then reads as its small label.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("metric-card")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.