The KPI card of an admin dashboard: a label, one big number, the change as a coloured pill with an arrow, a comparison line, an optional icon and room for a sparkline, with a loading state at the parts' own size. When the numbers change the value rolls digit by digit, the delta's arrow turns to its new direction and the sparkline tweens. StatGroup sets several on one surface with hairlines between them, four across, then two, then one, by container queries.
See it as an AI agent does.See this component the way an AI agent does.
Installation
npx shadcn@latest add @keyframery/statThis adds components/keyframery/stat.tsx and its primitive to your project, and installs UI SDK. The motion tokens are added to your global CSS the first time you install a component.
Usage
import { Stat } from "@/components/keyframery/stat"
export default function Usage() {
return <Stat label="Revenue" value={48210} formatValue={(v) => `$${v.toLocaleString("en-US")}`} delta={0.124} />
}Examples
A stat with every part
The label, an icon, the value, the delta with its comparison, and a sparkline that takes the delta's colour.
A row of stats
StatGroup puts stats on one surface with hairlines between them: four across on a wide container, two, then one. Refunds should fall, so downIsGood colours their fall green.
Loading at its own size
While loading, each part keeps its geometry as a soft block; when it ends the numbers fade back in, one part after another.
Motion
| Move | What you see |
|---|---|
| Cascade | On arrival the label, value, delta and chart rise out of a light blur one after another; when loading ends their ink comes back in the same order. |
| Roll | The value and the delta roll digit by digit to each new number, the right-hand digits a beat ahead. |
| Spring | The delta's arrow turns to its new direction (up, down or level) on a spring; its colour, which means status, switches at once. |
| Draw | A sparkline in the stat draws itself and tweens into the new period's shape. |
Timing and springiness follow the motion style you set. To change how fast this stat moves, pass speed:
<Stat speed="fast">
…
</Stat>"fast" is 0.6×, "slow" 1.4×, and a number sets the multiplier. With reduced motion turned on, nothing moves: changes happen at once or with a short fade.
Theming
Set these CSS variables on the component or a parent. Leave them unset to follow the light and dark theme. The open Customize panel below the preview lets you try these settings.
| Variable | What it changes | Default |
|---|---|---|
--stat-surface | The card, and the group's shared surface | --background; --card in dark |
--stat-divider | The hairlines between stats in a group | --border |
--stat-label | The label | --muted-foreground |
--stat-positive | Good news: the delta and the sparkline | oklch(0.55 0.15 150); oklch(0.74 0.16 150) in dark |
--stat-negative | Bad news: the delta and the sparkline | --destructive |
--stat-value-size | The number's size | 28px |
--stat-radius | The corners | 16px |
--stat-padding | The inset | 1.25rem |
--stat-group-columns | Columns in a group on a wide container | 4 |
--stat-chart-height | The height of a sparkline in StatChart | 2.75rem |
API reference
Every part takes className and children, along with the props of the element it renders. The parts are rendered by UI SDK, so they also take render, to draw your own element, and a function of their state for className and style.
Stat
Renders a <div>, and takes its props too.
Prop
Type
StatGroup
Renders a <div>, and takes its props too.
Prop
Type
Roll
Prop
Type
Other parts
These take the props of the element they render, and nothing else:
StatChart: a<div>StatComparison: a<div>StatDelta: a<div>StatIcon: a<div>StatLabel: a<div>StatValue: a<div>
Keyboard
| Key | What it does |
|---|---|
| Tab | A stat takes no focus of its own; Tab reaches a sparkline inside it, whose points take the arrow keys. |
Accessibility
Roles, keyboard and focus are declared on the component's UI SDK primitive, and state is announced through the matching ARIA attributes. More in Accessibility.
Built on UI SDK's core
UI SDK doesn't ship a stat, so this one is defined with its core: one definePrimitive in components/keyframery/core/stat-core.ts, with no React in it. UI SDK's adapters can render that same definition in Vue, Svelte, Solid and web components. To keep your own styling and take only the motion, import from @/components/keyframery/primitives/stat.
Questions
How does the animated Stat for UI SDK move?
Cascade: On arrival the label, value, delta and chart rise out of a light blur one after another; when loading ends their ink comes back in the same order. Roll: The value and the delta roll digit by digit to each new number, the right-hand digits a beat ahead. Spring: The delta's arrow turns to its new direction (up, down or level) on a spring; its colour, which means status, switches at once. Draw: A sparkline in the stat draws itself and tweens into the new period's shape.
Do I need Motion or Framer Motion for the animated Stat?
No. Every move is plain CSS, so there is nothing to install besides the component and UI SDK.
UI SDK has no stat. How is this one built on UI SDK?
Its behaviour is one definition written with UI SDK's core (definePrimitive), in components/keyframery/core/stat-core.ts. Its parts are rendered by UI SDK's adapter, so they take render, state-based class names and data-slot, like every UI SDK component.
What happens to the Stat when someone turns on reduced motion?
Nothing moves. State changes happen at once, or with a short fade.
More in Data
All componentsSparkline
A word-sized trend in plain SVG and CSS, no charting library: a line, an area or a row of bars from a list of numbers, with its last point marked. It draws itself on arrival, tweens into new data (a week into a month and back), colours itself by its news if you ask, and lets people scrub it with the pointer or the arrow keys while its value rolls in a small readout. Its trend and change are readable by screen readers and agents.
Table
Rows cascade in, a sortable header's arrow turns over on a spring and reports the sort to screen readers, and selected rows fade in. On a phone it scrolls sideways with a soft edge.