Skip to content
WunderUI

KPI

Pro

One figure with its label and optionally its change: a framed card with a dot and delta, a plain card with a caption, or a bare inline figure.

Playground

+12.4%

Revenue

$48,200

Installation

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

Then import what you need:

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

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 for

  • KPI Group for several figures in one frame, divided by hairlines
  • Metric Card for a figure with a trend chip, a sparkline, progress or a menu
  • Number Value for a headline figure that counts up and shows its change as one unit

Style

Trend is the default, with a dot and a delta above the label. Simple drops them for a caption under the value, and Inline has no frame, so it fits in a header or a sentence.

+12.4%

Revenue

$48,200

Change

You pass the change as a finished string and set its arrow. A separate flag sets the colour, so falling churn points down and stays green, and rising tickets point up in red.

+12.4%

Revenue

$48,200

Number format

The card formats nothing. Write the English format yourself, with the comma, currency sign and unit.

+3.2%

Average contract

$1,842.50

Content

A previous value adds a Prev line under the figure, and a long label wraps so the card grows. A figure without spaces does not wrap, so keep it short.

+12.4%

Revenue

$48,200

Behavior and motion

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

The figure shows the trend style with a previous value. Simple has no dot, delta or previous line but adds a caption, and inline is only the value over its label, without the card.

+12.4%

Revenue

$48,200

Prev: $42,880

  • data-slot="stat-card"

    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.

  • Optional

    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.

  • Optional

    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.

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

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

  • Optional

    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.

  • Do

    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.

  • Do

    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.

  • Do

    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.

  • Do

    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

    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

    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

    Don't set delta, previous or dot colour on the simple or inline style. Those styles don't draw them.

API reference

One table for StatCard. It is a plain component, so the table lists every prop.

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.

PropTypeDefaultDescription
label requiredstring—What the figure is, for example . Required. It wraps when it is long.
value requiredstring—The figure as a finished string, for example , or . Required. It is not formatted, and a figure without spaces does not wrap.
variant"trend" | "simple" | "inline""trend"The layout. draws the dot, the delta and the previous value, draws a caption under the value, draws the bare value over the label with no frame. Defaults to .
deltastring—The change, as a finished string with its sign, for example . Shown by the style only, with an arrow. Without it the top row shows the dot alone.
trend"up" | "down""up"Which way the arrow points. Defaults to . There is no neutral value: leave out instead.
trendGoodbooleantrueWhether the change is good, which sets the colour of the delta and its arrow: green for true, red for false. Defaults to true.
prevstring—The previous value, shown under the figure as followed by this string. style only.
dotColorstring"var(--primary)"Any CSS colour for the dot, for example . Defaults to . style only.
captionReactNode—A line under the value, for example . style only; it can hold more than text, so a state message with a retry button fits.
classNamestring—Extra classes for the root, for example a width. The inline style has no frame, so a width there only sizes the text.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("kpi")
InstallIncluded in Core and Pro

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