# Stat Band
> A row of two to four big figures, each with a short label, an optional note, and an optional small chart, for an About page or a landing page.
- Name: `stat-band`
- Status: beta
- Categories: stats, numbers, marketing, about
- Files: the install writes `stat-band.tsx`, and any part files named `stat-band-*.tsx`, to your `components` alias, `@/components` by default. Edit them freely. They are yours.
- Other registry items: `@arbokui/rolling-number`, `@arbokui/motion-timing`, `@arbokui/glide-highlight`. The install adds them.
- Gallery: https://arbokui.com/website/stat-band
- Registry item: https://arbokui.com/r/stat-band.json
## Install
1. Add the registry to `components.json`. Do this first, once:
```bash
npx shadcn@latest registry add "@arbokui=https://arbokui.com/r/{name}.json"
```
The command writes this entry. You can also add it by hand:
```json
{
"registries": {
"@arbokui": "https://arbokui.com/r/{name}.json"
}
}
```
Without this step, the shadcn CLI looks up `@arbokui` in a public list that Arbokui does not control.
2. Add the theme once per app. It replaces your color tokens with ones checked for contrast:
```bash
npx shadcn@latest add @arbokui/theme
```
3. Add the website component. It also adds every component it uses:
```bash
npx shadcn@latest add @arbokui/stat-band
```
## Use it for
- Facts about a company or product on a marketing page, like people, offices, and the year it started. Put a Headline above it.
- Write each \`value\` as it should read, like "40", "1,800", "$4.2M", or "24/7". Its digits roll in once, when the band scrolls into view. Text with no digits just shows.
- Keep each \`label\` to a few words, and the \`note\` to one short line.
- Give a figure a \`chart\` of the numbers behind it. "bars" suits counts, and "line" suits a trend. Both start from zero. A chart has no axis, so say what it covers in the \`note\`, like "Each year since 2018".
- Two figures sit side by side at any width. Three stack until there is room for a row. Four go two by two, then four in a row from 40rem of the band's width.
- Keep figures short, like "1,800" or "12k". One wider than that, like "$4.2M" or "1,250,000", makes the whole band stack on phones and wait for more room for a row.
## Avoid it for
- Numbers in an app's dashboard, with a change, a loading state, or an empty state. Use Stats Cards, which shows each one in a card.
- Figures you cannot back up, like an uptime or a customer count. Say only what is true.
- More than four figures. Pick the four that matter most.
- Words as a value. Put the words in the label.
- A chart on only some figures. Give every figure one, or none, so the cells line up.
## Props
- `items`: `StatBandItem[]`. Default `[]`. The figures, in order. With none, nothing renders.
- `className`: `string`. Extra classes on the root, which holds the container query.
- `StatBandItem`: `{ value: string; label: ReactNode; note?: ReactNode; chart?: StatBandChart }`. Type. One figure.
- `StatBandChart`: `{ shape: "bars" | "line"; values: readonly number[]; label: string }`. Type. A small chart under a figure. shape picks bars or a line, values run oldest first, and label names the chart for screen readers.
## Accessibility
- The figures are a list. Screen readers hear each value, then its label and note, like "40, People, Across 12 countries".
- Screen readers hear the real value even before the digits roll. The rolling digits are hidden from them.
- The server sends the real values, so the page reads right with no script, and before it loads.
- The digits roll, and a chart draws in, only when they start below the screen. Reduced motion, motion off, and print show them at rest.
- A chart is one image to screen readers. They hear its label with the first and last values, like "People each year, 2018 to 2025: 6 to 40".
- The newest bar, or the dot at the end of the line, takes the text color. The other bars take the 3:1 line color, and forced colors keep them. A long series draws as one light shape, edged in that 3:1 color.
- A chart runs left to right on a right-to-left page too, like the digits.
- Nothing in it takes focus. The hover fill is for the pointer only.
## Examples
### Four figures about a company, under a Headline
```tsx
```
### Two figures, each with a chart of the numbers behind it
```tsx
```
### Two figures side by side
```tsx
```