---
id: "packages/active-ui/stat-card"
title: "StatCard"
description: "One key figure on a card - a title, an already formatted value, an optional trend, and optionally a link to the details."
url: "/packages/active-ui/stat-card"
locale: "en"
revision: "0068530215f9a383"
---
# StatCard
`StatCard` shows one key figure of a dashboard: the number of participants, the contributions of a
month. The value arrives formatted. A trend beside it shows the change and whether it is good
news; with `href` the whole card links to the details. For label and value pairs that are not key
figures, use a [DescriptionList](/packages/active-ui/description-list).
**Example: Three key figures**
Client: Runs entirely in your browser. Source: `examples/ui/stat-card.tsx`.
```tsx
// apps/docs/examples/ui/stat-card.tsx
import {FileWarningIcon, UsersIcon, WalletIcon} from 'lucide-react';
import {formatNumber} from '@workspace/active-format';
import {StatCard} from '@workspace/active-ui/components/composed/stat-card';
/**
* Three key figures. The values arrive formatted; the first card has a
* rising trend, the second a falling one, and the third links to its
* details. The figures are fictitious.
*/
export default function StatCardExample() {
return (
}
trend={{value: '+3.1%', timeframe: 'this year', positive: true}}
/>
}
trend={{value: '-0.8%', timeframe: 'this month', positive: false}}
description="Received in October"
/>
}
href="#returned"
description="Open the list"
/>
);
}
```
## What the composition adds
- **A formatted value only**: `value` is a string, so a bare number cannot slip through
unformatted. Format it with [active-format](/packages/active-format), as the example does.
- **The title as a heading**, `` by default; `headingLevel={3}` when the cards sit in a section
that already has an ``.
- **A trend** with an arrow and a tone: up and green when `positive`, down and red when not, and
the period beside it.
- **A link card** with `href`, through your router's link with `linkComponent`.
## Usage
```tsx
import {StatCard} from '@workspace/active-ui/components/composed/stat-card';
;
```
## What your application provides
- The formatted value and trend, including its sign: the arrow is decoration and is not read out.
- The heading level that fits the page, and `linkComponent` for client-side navigation.
## Accessibility
- With `href` the card is one link, named by its whole text.
- The icon is decorative and hidden from assistive technology.
## API
| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `string` | yes | The name of the figure, as a heading (see `headingLevel`). Translated. |
| `value` | `string` | yes | The **already formatted** value of the tile. Deliberately a `string` and not `string \| number`. A bare number is rendered literally by React: the dashboard would show `12480` where the grid next to it reads `12.480`. The fix is **not** in this component but in the type. A KPI cell does not know what its number means (a count, an already formatted amount, a percentage, an identifier), and a component that guesses the unit will one day guess it wrong. The call site does know, and supplies the text: `formatNumber(count, 'integer', presentation)` for a count, `formatCurrency(...)` for an amount. As a `string`, a bare number is a compiler error, exactly where the semantics are known. |
| `className` | `string` | no | Classes for the card, or for the link around it with `href`. |
| `description` | `string` | no | A short line below the value. |
| `headingLevel` | `StatCardHeadingLevel` | no | The heading level of {@link StatCardProps.title}. Default: `2`. **Why the default is `2`.** The title is a section heading and not a loose label: the tile is a bounded block with its own subject, and with `href` it is also a destination of its own. Below the `