# Stat

> Displays a labelled metric with an optional trend indicator. For dashboards and summary rows.

URL: https://apogee.avaui.dev/docs/stat
Last updated: 2026-10-15

Displays a labelled metric with an optional trend indicator. For dashboards and summary rows.

Last updated October 15, 2026

```astro
<Stat label="Revenue" value="$48,900" change="+12%" trend="up" />
<Stat label="Refunds" value="$1,204" change="-4%" trend="down" />
<Stat label="Active users" value="2,318" />
```

## Add

```sh
npx @ava-ui/apogee add stat
```

No Apogee component dependencies. Depends on `@lucide/astro` for the arrows.

## Usage

```astro
---
import Stat from '@/components/apogee/Stat/Stat.astro'
---
<Stat label="Revenue" value="$48,900" change="+12%" trend="up" />
```

## API

`@composable` — exposed to Content Editors in AVA. Any other attribute passes through to the root `<div>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | The metric’s name. |
| `value` | `string` | — | The metric’s value, rendered large and bold. Not formatted — bring your own currency/percent formatting. |
| `change` | `string` | — | Optional change indicator text, e.g. `"+12%"`. |
| `trend` | `'up' \| 'down'` | `'up'` | Colours the change and picks the arrow direction. |
| `changeStyle` | `'simple' \| 'trend' \| 'modern'` | `'trend'` | A plain arrow, a trend line, or a bordered pill where only the arrow is coloured. |
| `comparison` | `string` | — | Text after the change, e.g. `"vs last month"`. |
| `size` | `'medium' \| 'large'` | `'medium'` | Value size. |
| `class` | `string` | — | Extra classes, merged last. |

Slot `start` takes a FeaturedIcon beside the stack.

## Variants

Every `changeStyle`:

```astro
<Stat label="Revenue" value="$48,900" change="12%" changeStyle="simple" />
<Stat label="Revenue" value="$48,900" change="12%" changeStyle="trend" />
<Stat label="Revenue" value="$48,900" change="12%" changeStyle="modern" />
```

Comparison, a leading icon, and the large size:

```astro
<Stat label="Customers" value="2,318" change="8%" comparison="vs last month" />
<Stat label="Members" value="48" change="2" comparison="this week"><FeaturedIcon slot="start" color="primary"><Users /></FeaturedIcon></Stat>
<Stat size="large" label="Annual revenue" value="$1.2M" />
```

A metric card: Card with a footer link.

```astro
<Card padding="none">
<div class="p-5"><Stat label="Active users" value="2,318" change="8%" comparison="vs last month" changeStyle="modern" /></div>
<Button slot="footer" variant="link" size="small" class="ms-auto">View report</Button>
</Card>
```

Up and down:

The change can go up or down, or be left out:

```astro
<Stat label="Signups" value="1,204" change="+18%" trend="up" />
<Stat label="Churn" value="2.1%" change="+0.4%" trend="down" />
<Stat label="Sessions" value="9,540" />
```

## States

Static display — Stat renders plain text and an icon, no hover, focus, disabled, or loading state applies.

## Examples

Stats stack cleanly in a row or column — `tabular-nums` keeps the digits aligned:

```astro
<div class="flex flex-col gap-4">
<Stat label="This month" value="$48,900" change="+12%" trend="up" />
<Stat label="Last month" value="$43,650" change="+6%" trend="up" />
</div>
```

## Accessibility

-   Label, value, and change render as plain text in DOM order — a screen reader announces all three, not just the icon.
-   The trend is conveyed by the `change` text itself (`"+12%"` / `"-4%"`), not color alone; the arrow icon is `aria-hidden`.
-   Native semantics, no extra ARIA needed.

## Tokens

| Token | Used for |
| --- | --- |
| `--foreground-neutral-faded` | Label color |
| `--foreground-neutral` | Value color |
| `--foreground-positive` | Positive change text + icon (default when `trend` is omitted) |
| `--foreground-critical` | Negative change text + icon (`trend="down"`) |

## Do / Don’t

-   **Do** keep `label` to one to three words so it reads at a glance.
-   **Do** pass `trend="down"` together with a negative `change` — the color and the number should agree.
-   **Don’t** vary the `value` format (currency symbol, decimal places) across stats shown together — keep a group consistent.
-   **Don’t** use Stat for a number with no context — always give it a `label`.

## Content

-   `value` is shown exactly as passed — format currency, percentages, and separators before handing it to the component.
-   `change` reads best as a signed delta or percentage (`"+12%"`, `"-4%"`, `"+128"`).
-   Labels are short nouns, sentence case, no ending punctuation.

## Related

[

MeterA native meter gauge for a measurement in a known range, like disk usage or a score.

](https://apogee.avaui.dev/docs/meter)[

BadgeA small status label — for counts, tags, and state indicators.

](https://apogee.avaui.dev/docs/badge)[

HeadingA semantic, fluid-sized heading — pick the tag with \`as\`, the visual size with \`size\`.

](https://apogee.avaui.dev/docs/heading)