# KPI Group

A row of KPIs sharing one bordered container.

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

## Install

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

## Import

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

## Minimal usage

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

- [KPI](https://wunderui.com/components/kpi) for a single figure, or cards that should keep their own frame
- [Metric Group](https://wunderui.com/components/metric-group) for cards with a trend chip, a chart, progress or a menu
- [Table](https://wunderui.com/components/table) for many figures to compare in rows and columns

## Behavior

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

- `KPIGroup`: 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.
- `Cell`: 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.
- `Divider`: 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.
- Keep the cells alike. Give every cell a delta or none, so the labels of a row start at the same height.
- 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.
- 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 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 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 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

### KPIGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | ReactNode |  | The cells, usually StatCard. Every direct child loses its border, radius and shadow and gets the card surface. |
| className | string |  | Extra classes for the grid, for example a width or a different gap. The grid is full width by default. |
| columns | 2 \| 3 \| 4 | 4 | The widest layout. One column below `sm`; 2 and 3 apply from `sm`, 4 shows two columns from `sm` and four from `lg`. Defaults to 4. |

## Examples

### Columns: two, three or four

### Cell style: trend or simple

### Cells: a full row, mixed heights

## In context

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

One group above a dashboard. A fall in conversion is bad and turns red; a fall in open tickets is good and stays green.

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

The group has no states of its own. Use a skeleton while loading, an Empty State or Alert when empty or failed, and a warning that says how old stale figures are.

### Billing: simple cells under a heading

Four facts about a plan in the simple style. With no deltas, the captions carry the context.

## For AI agents

`get_component("kpi-group")`

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