Skip to content
WunderUI

KPI Group

Pro

A row of KPIs in one bordered frame, divided by thin 1 px lines.

Playground

+12.4%

Revenue

$48,200

+6.8%

Active users

1,842

+0.4 pts

Conversion rate

3.6%

-0.4%

Churn rate

2.1%

Installation

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

Then import what you need:

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

Then use it:

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

export function Overview() {
  return (
    <KPIGroup columns={4}>
      <StatCard label="Revenue" value="$48,200" delta="+12.4%" trend="up" />
      <StatCard label="Active users" value="1,842" delta="+6.8%" trend="up" />
      <StatCard label="Conversion rate" value="3.6%" delta="+0.4 pts" trend="up" />
      <StatCard label="Churn rate" value="2.1%" delta="-0.4%" trend="down" />
    </KPIGroup>
  )
}

Expected result: You see one framed row of four figures divided by thin lines: Revenue, Active users, Conversion rate and Churn rate, each with its change.

When to use

Use KPI Group for

  • The row of figures at the top of a dashboard or a report
  • Several figures that share one period and one frame
  • A summary of a plan, a project or an account in the simple style

Use something else for

  • KPI for a single figure, or cards that should keep their own frame
  • Metric Group for cards with a trend chip, a chart, progress or a menu
  • Table for many figures to compare in rows and columns

Columns

The widest layout is 2, 3 or 4 columns, and narrow screens get one. The layout follows the window, not the box the group sits in.

+12.4%

Revenue

$48,200

+6.8%

Active users

1,842

Cell style

Any StatCard works as a cell. The group removes the cell's border, radius and shadow, so a card never sits in a card.

+12.4%

Revenue

$48,200

+6.8%

Active users

1,842

+0.4 pts

Conversion rate

3.6%

-0.4%

Churn rate

2.1%

Cells

Cells in a row are as tall as the tallest one. Pass as many cells as columns, because a row that is not full shows empty slots in the border colour.

+12.4%

Revenue

$48,200

+6.8%

Active users

1,842

+0.4 pts

Conversion rate

3.6%

-0.4%

Churn rate

2.1%

Behavior and motion

What the group renders and how it lays out its cells.

Static
KPIGroup is static: no focus, no hover state, no handlers. The cells are whatever you put in.
Columns
Columns is 2, 3 or 4 (default 4) and collapses to one column on small screens. Breakpoints follow the window width, not the group's container, so four columns can end up in a narrow box.
Equal heights
The group is a grid, so the cells of a row stretch to the tallest. Content stays at the top, so a cell with a shorter top row has its label a little higher.
A row that is not full
A row with fewer cells than columns leaves empty slots that show the border colour behind the grid. Pass as many cells as columns.
Frame
The group clips its cells to its 12 px radius and draws the border. Direct children lose their own border, radius and shadow and get the card surface, even a non-card like a skeleton cell.
Props
Only children, columns and a class are read. Other props, such as role or aria-label, aren't forwarded to the grid.
Reading
The group adds no role or label. A screen reader reads the cells in order, each as its own card, so name the group with a heading before it.
States
There is no loading, empty or error state. The Examples tab shows a skeleton group, an Empty State, an Alert and a warning above stale figures.
Motion
None. The cells appear as they are and the group doesn't animate when they change.
Reduced motion
There is no motion, so reduced motion changes nothing.

Anatomy

The figure shows a group of two cells. The group draws the frame and the hairlines; the cells draw their own content.

+12.4%

Revenue

$48,200

-0.4%

Churn rate

2.1%

  • data-slot="kpi-group"

    A grid with a 1 px border and a 12 px radius, with the border colour as background so the 1 px gaps between cells draw the hairlines. It clips its cells to its radius.

  • Any child, usually a StatCard. The group strips the border, radius and shadow from direct children so a card doesn't sit in a card, and cells in a row stretch to the same height.

  • Optional

    The 1 px hairline between two cells. It is the gap of the grid, not an element: vertical between side-by-side cells, horizontal when they stack.

Best practices

  • Do

    Use as many cells as columns: 2, 3 or 4. The group is one row, and no slot is left empty.

  • Do

    Keep the cells alike. Give every cell a delta or none, so the labels of a row start at the same height.

  • Do

    Use four columns for a full-width dashboard row and fewer inside a narrower page. Breakpoints follow the window, not the box the group sits in.

  • Do

    Name the period once, in a heading or a caption next to the group, so the cells do not repeat it.

  • Don’t

    Don't leave a row half full. The empty slots show the border colour, so the last row reads as a grey block with a hole in it.

  • Don’t

    Don't put cards with their own frame next to the group and call it one row. The cells belong to the group and have no border of their own.

  • Don’t

    Don't use the group to line up a few unrelated figures. Use it for figures that belong to one period and one question; for separate cards use a grid.

  • Don’t

    Don't pass role, aria-label or other attributes to the group and expect them on the grid. It takes only children, columns and a class; wrap it in your own element.

API reference

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

A grid with a 1 px border and a 12 px radius, with the border colour as background so the 1 px gaps between cells draw the hairlines. It clips its cells to its radius.

PropTypeDefaultDescription
children requiredReactNode—The cells, usually StatCard. Every direct child loses its border, radius and shadow and gets the card surface.
columns2 | 3 | 44The widest layout. One column below ; 2 and 3 apply from , 4 shows two columns from and four from . Defaults to 4.
classNamestring—Extra classes for the grid, for example a width or a different gap. The grid is full width by default.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("kpi-group")
InstallIncluded in Core and Pro

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