# Animated Counter

> A React animated counter that rolls each digit to its new value like an odometer, for stats, prices, timers and live numbers.

- Type: React chart component (Charts & Stats)
- Access: Free (the source is open to everyone)
- Version: 1.0.1
- Install: `npx wingo-ui@latest add animated-counter`
- Docs: https://wingo-ui.com/components/animated-counter

## Interaction

Drag along the ruler, or focus it and use the arrow keys, to change the value. Digits roll up as the number grows and back down as it shrinks, fading in and out at the top and bottom of each window rather than being cut off. A number that keeps changing spins instead of stuttering. The width always matches the number: a place that is gained slides in, one that is lost fades out while the rest close up, and the separators glide along with them.

## Installation

```bash
npx wingo-ui@latest add animated-counter
```

The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add https://wingo-ui.com/r/animated-counter.json`

Files:

- `components/ui/animated-counter.tsx`

npm dependencies: `npm i motion`

Wingo UI dependencies (installed automatically):

- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
"use client"

import { AnimatedCounter } from "@/components/ui/animated-counter"

export function Revenue({ total }: { total: number }) {
  return <AnimatedCounter value={total} size="lg" weight="medium" />
}

// money: two decimals and a currency mark that stays put
// <AnimatedCounter value={total} decimals={2} prefix={<span>₹</span>} grouping="indian" />

// fixed width, so a timer never shifts as it rolls over
// <AnimatedCounter value={seconds} padStart={4} separator="" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` |  | The number to show. Each change animates from whatever is on screen, so it can be updated as often as you like. Negative values get a leading minus. |
| `decimals?` | `number` | `0` | How many decimal places to keep, up to 15. The value is rounded to that precision, so the wheels always land on a whole digit. |
| `duration?` | `number` | `0.6` | Roughly how many seconds a digit takes to settle on its new face. Lower it when the value updates continuously, so the wheels stay close to the number. |
| `padStart?` | `number` | `1` | Fewest whole digits to show, up to 24, padded with leading zeros. Use it to hold the width steady when the number crosses a power of ten. |
| `separator?` | `string` | `","` | Placed between digit groups. Pass an empty string to group nothing. |
| `decimalSeparator?` | `string` | `"."` | Character between the whole and decimal digits. |
| `locale?` | `string` | `""` | Intl locale whose group and decimal marks replace separator and decimalSeparator, unless you pass those: "en-US" writes 1,234.5, "de-DE" 1.234,5, "fr-FR" 1 234,5. Falls back to UIProvider's locale; empty keeps the separators. |
| `grouping?` | `"western" \| "indian"` | `"western"` | Where the separators land. Western groups every three digits, 1,234,567. Indian groups the last three then pairs, 12,34,567. |
| `size?` | `"inherit" \| "sm" \| "md" \| "lg" \| "xl"` | `"inherit"` | Font size: 24px (sm), 36px (md), 60px (lg) or 72px (xl). Inherit takes the size of the surrounding text, so a text class on the counter or its parent sizes it instead. |
| `font?` | `"inherit" \| "sans" \| "mono" \| "serif"` | `"inherit"` | Font family from your theme tokens. Figures are tabular in every family, so the width only changes when a place is gained or lost. |
| `weight?` | `"inherit" \| "normal" \| "medium" \| "semibold" \| "bold"` | `"inherit"` | Font weight of the digits, the separators and any string prefix or suffix. |
| `color?` | `string` | `"currentColor"` | Text color, any CSS color. currentColor follows the surrounding text, so it adapts to light and dark on its own. |
| `fade?` | `boolean` | `true` | Fades each digit window at its top and bottom edge, so rolling faces blur in and out. Turn it off for a hard cut like a mechanical counter. |
| `fadeSize?` | `number` | `22` | How deep the top and bottom fade of each digit reaches, as a percent of the line box. Only with fade on. |
| `bounce?` | `number` | `0.18` | Spring bounce of the wheels and the width changes, from 0 (settles with no overshoot) to 1. |
| `prefix?` | `ReactNode` |  | Rendered before the number, for a currency mark or an icon. It sits outside the wheels and never animates, but glides when the width changes. |
| `suffix?` | `ReactNode` |  | Rendered after the number, for a unit or a percent sign. |
| `className?` | `string` |  | Extra classes merged onto the root element (data-slot="animated-counter"). With size, font and weight left on inherit it styles like text, so a text class here or on a parent works too. The digit columns carry data-slot="animated-counter-digit" and the separators data-slot="animated-counter-mark", for reaching either from the root. |

## Examples

- **Revenue card**: Two decimals and a dollar prefix; add an order and the total rolls up while the order count ticks along.
- **Live value**: A shorter duration keeps the wheels close to a number that updates every second or so.
- **Countdown timer**: padStart 2 and no separator hold minutes and seconds at a fixed width.
- **Locales and grouping**: locale picks the group and decimal marks; grouping indian puts separators after the last three digits, then every two.

## See also

- [Stat Card](https://wingo-ui.com/components/stat-card) ([Markdown](https://wingo-ui.com/components/stat-card.md))
- [Number format](https://wingo-ui.com/components/number-format) ([Markdown](https://wingo-ui.com/components/number-format.md))
- [Countdown](https://wingo-ui.com/components/countdown) ([Markdown](https://wingo-ui.com/components/countdown.md))
- [Trend badge](https://wingo-ui.com/components/trend-badge) ([Markdown](https://wingo-ui.com/components/trend-badge.md))
- [KPI Dashboard](https://wingo-ui.com/components/kpi-dashboard) ([Markdown](https://wingo-ui.com/components/kpi-dashboard.md))

---

Canonical: https://wingo-ui.com/components/animated-counter
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt