---
title: Stats
description: Statistics group container — responsive grid of stat cards with optional cascading entrance animation
visibility: guest
---

# Stats

Container component for a group of `<x-wirekit::stat>` cards. Responsive auto-fit grid by default (each stat sits in a column at least 200 px wide); pass `cols="2|3|4|5"` to pin a specific column count. Optional `stagger` prop cascades child entrance animations.

## Basic Usage

:::preview{title="Auto-fit stats grid (default)"}
<x-wirekit::stats>
    <x-wirekit::stat label="Builds / day" value="125,000" />
    <x-wirekit::stat label="Avg deploy" value="847" description="ms" />
    <x-wirekit::stat label="Uptime" value="99.99%" />
</x-wirekit::stats>
:::

## Fixed Column Count

:::preview{title="Three-column stats grid"}
<x-wirekit::stats cols="3">
    <x-wirekit::stat label="Revenue" value="$2.4M" change="+12%" trend="up" />
    <x-wirekit::stat label="Customers" value="8,247" change="+340" trend="up" />
    <x-wirekit::stat label="Churn" value="0.8%" change="-0.2%" trend="down" />
</x-wirekit::stats>
:::

## Cascading Stagger

Pair `stagger` with `animateIn` on each stat to cascade entrance animations:

:::preview{title="Stats with 75ms stagger"}
<x-wirekit::stats cols="3" stagger>
    <x-wirekit::stat animateIn="slide-up" animate label="Builds / day" value="125000" />
    <x-wirekit::stat animateIn="slide-up" animate label="Avg deploy" value="847" description="ms" />
    <x-wirekit::stat animateIn="slide-up" animate label="Customer NPS" value="74" change="+8" trend="up" />
</x-wirekit::stats>
:::

`stagger` (boolean) uses the default 75ms step. Pass an integer for a custom rhythm:

```blade
<x-wirekit::stats cols="3" :stagger="125">
    {{-- each child waits an additional 125ms before its entrance fires --}}
</x-wirekit::stats>
```

Stagger uses CSS-only `:nth-child` rules — no JS — and caps at index 8 to avoid runaway delays on long lists. Honors `prefers-reduced-motion: reduce` (delays collapse to 0).

## Custom Stagger via CSS

The `stagger` prop emits a `.wk-stagger` class on the grid wrapper and sets `--wk-stagger-step` inline. You can also drive the stagger from CSS directly — useful when the step value depends on viewport size, external state, or a media query.

### CSS contract

| Selector | Effect |
|---|---|
| `.wk-stagger > *:nth-child(N)` | Each child gets `animation-delay: calc((N - 1) × var(--wk-stagger-step))`. |
| `--wk-stagger-step` | The per-child increment. Default `75ms` when emitted via the `stagger` prop. Overrideable per-instance via `style="--wk-stagger-step: …"` OR globally via `:root {}`. |
| Cap | `:nth-child(N)` rules cap at index 8 so the final visible delay stays under ~600 ms by default. |

### Example: slower cascade for a hero-stats row

:::preview{title="Custom --wk-stagger-step via inline style"}
<x-wirekit::stats cols="3" stagger style="--wk-stagger-step: 200ms;">
    <x-wirekit::stat animateIn="slide-up" label="Slow tier 1" value="1,200" />
    <x-wirekit::stat animateIn="slide-up" label="Slow tier 2" value="3,400" />
    <x-wirekit::stat animateIn="slide-up" label="Slow tier 3" value="5,600" />
</x-wirekit::stats>
:::

Honors `prefers-reduced-motion: reduce` — every child's delay collapses to 0 inside the global reduced-motion block, regardless of the `--wk-stagger-step` value.

See [Public CSS API → wk-stagger](../extending/public-css-api.md#animation--motion) for the full contract + stability tier.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `cols` | `'2'` \| `'3'` \| `'4'` \| `'5'` \| `null` | `null` (auto-fit) | Column count tier. `null` produces an auto-fit grid (each column ≥ 200px). Pinned values are responsive — mobile gets a single column, sm+ scales up. |
| `stagger` | `bool` \| `int` \| `null` | `null` | Cascade entrance animations across direct children. `true` = 75 ms step; integer = custom millisecond step; `null` (default) = no stagger. |
| `scope` | `string` \| `null` | `null` | Scoped personalization name. |

## Keyboard Interaction

Layout wrapper — keyboard interaction is delegated to the `<x-wirekit::stat>` children.

## Design Tokens

| Token | Used for |
| --- | --- |
| `--space-wk-md` | Inter-stat grid gap |
| `--font-wk-sans` | Stat label / value typography |
| `--wk-stagger-step` | Per-child delay when `stagger` is set (default 75 ms) |

## See Also

- [Stat](stat.md) — the individual stat card component used inside `<x-wirekit::stats>`.
- [Feature Grid](feature-grid.md) — sibling container for `<x-wirekit::feature>` cards, also supports `stagger`.
- [Public CSS API — wk-stagger](../extending/public-css-api.md#animation--motion) — full contract for the stagger emission.
- [Animations](../animations.md) — `animateIn` preset catalog.