Stats band
Headline numbers that count up in view, each with a tiny visual that proves it and a context line on hover, plain or in a hairline grid.
pnpm dlx shadcn@latest add @uiarc/stats-bandLive block · sample data
- Marketing pages that back a claim with a few numbers.
- About and investor pages with headline metrics.
- Live product metrics with trends. Use Metric card or Metrics dashboard.
- More than four numbers. Split them or use a table.
Installation
Add Stats band with the shadcn CLI, or copy the source by hand.
pnpm dlx shadcn@latest add @uiarc/stats-bandAdds the block and its local dependencies, and installs motion. First time? Add the @uiarc registry to components.json, or use the full URL:
Usage
Use this under a hero or between sections to back a claim with numbers. Replace the sample stats in stats-band-data.ts.
example.tsx
import { StatsBand } from "@/registry/blocks/stats-band/stats-band"; export function Numbers() { return ( <StatsBand layout="divided" stats={[ { value: 2_334_000, notation: "compact", decimals: 1, label: "Deploys in the last 12 months", detail: "Across 12,400 teams", context: "Up from 1.4M the year before", visual: { kind: "trend", values: [141, 148, 139, 162, 171, 184, 196, 203, 221, 238, 257, 274] }, }, { value: 38, suffix: "ms", label: "Median response time", detail: "At the edge, worldwide" }, { value: 35, label: "Edge regions on six continents", visual: { kind: "map", points: [[-122.4, 37.8], [-0.1, 51.5], [139.7, 35.7]] } }, ]} /> );}Built fromSegmented control
StatsBand
A band of three or four headline numbers, each with an optional tiny visual that proves it. Numbers count up in sequence as the band enters view, then the visuals draw in; hover or focus reveals one line of context.
PropTypeDefaultDescription
statsStat[]statsEach has value and label, plus optional prefix, suffix, decimals, notation ("compact" for 2.3M), detail, context (the hover line), and visual: a trend, uptime strip, latency distribution, or world map. Every visual is optional.layout"plain" | "divided""plain"plain lets the stats float on whitespace; divided sets them in a hairline grid ruled above and below.titlestring–Optional heading above the band. Without it the band is labelled "Key numbers".descriptionstring–Optional line under the heading.durationnumber1.6Seconds each number takes to count up.localestring"en-US"Number formatting locale. Fixed by default so server and client agree.classNamestring–Extra class on the section.- Stats are a description list: the label is the term, the number, detail, and context are its descriptions. Screen readers get both the detail and the context line.
- Stats with a context line are focusable, so keyboard and touch users reveal it too. Visuals are decorative and aria-hidden; the copy carries the meaning.
- Screen readers get the final formatted value once; the counting digits are aria-hidden.
- The section is labelled by the title or, without one, by "Key numbers".
- Each number counts from zero with a strong ease out over 1.6s, staggered 90ms per stat, the first time the band is half in view.
- Digits are tabular and the final value reserves the width underneath, so nothing shifts while counting.
- Stats rise 8px and fade in; in the divided layout the top and bottom rules draw across and the hairlines grow between stats.
- Once a number has mostly landed, its visual draws in: the sparkline and map wipe in from the left, bars grow from the baseline in a short sweep, and the trend end dot settles last.
- Hover or focus cross-fades the detail line to the context line and gives that stat's visual the accent; the others stay neutral.
- Reduced motion shows final values, lines, and visuals at once.
- One row of up to four stats, two columns below 760px container width, one column below 420px.
- Dividers reflow with the grid: vertical between neighbours, horizontal between rows.
- Number size scales with container width between 36px and 72px.
- Counting writes text straight to the DOM from one Motion tween per stat; React does not rerender per frame.
- One IntersectionObserver for the band, disconnected after the first view.
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
- Use three or four stats with specific, verifiable numbers. Round numbers read as made up.
- Put units in suffix (%, ms, +, /5) so they render smaller and muted beside the number. Use notation: "compact" for large counts; it counts within its final unit.
- Give each stat a visual that proves the number, and a context line that compares it (up from, down from, p95). Leave both out for a plain numbers band.
- Place it under a hero or between a features section and testimonials.
- Edit stats-band-data.ts to replace the sample numbers.
The full library index for assistants is at /llms.txt.