Premium & Brand

Animated Number

Number that springs to its target — counts up or down.

Import

tsx

import { AnimatedNumber } from "@cooud-ui/ui";

bash

npx cooud-ui add animated-number

Examples

Count up

Springs toward the target whenever it changes, so a balance or KPI counts up instead of snapping. Honours reduced-motion (snaps) and formats through Intl. Click to add a sale.

Receita do mêsR$ 12.480,00

tsx

function Revenue() {
  const [total, setTotal] = useState(12480);
  return (
    <div className="flex flex-col items-center gap-4">
      <AnimatedNumber
        value={total}
        locale="pt-BR"
        formatOptions={{ style: "currency", currency: "BRL" }}
        className="font-display text-4xl font-semibold text-fg"
      />
      <Button size="sm" variant="outline" onClick={() => setTotal((t) => t + 850)}>
        Nova venda
      </Button>
    </div>
  );
}

API Reference

Generated from the component's exported types.

AnimatedNumberProps

Extends Omit<React.ComponentPropsWithoutRef<typeof motion.span>, "children">

Prop	Type	Default	Description
`value`*	`number`	—	Target value. Whenever it changes, the number tweens from its current displayed value to here.
`format`	`(n: number) => string`	—	Custom formatter for the displayed string. When omitted, the value is formatted with `Intl.NumberFormat(locale, formatOptions)`.
`locale`	`string`	—	Locale passed to the default `Intl.NumberFormat` formatter (ignored if `format` is set).
`formatOptions`	`Intl.NumberFormatOptions`	—	Options passed to the default `Intl.NumberFormat` formatter (ignored if `format` is set).
`duration`	`number`	`0.8`	Tween length in seconds. Defaults to ~0.8s; overrides the spring's natural duration.
`spring`	`AnimatedNumberSpring`	—	Override the settle spring (advanced — defaults to the Cooud count spring).
`reducedMotion`	`"user" \| "always" \| "never"`	`"user"`	How `prefers-reduced-motion` is honoured. Defaults to `"user"` (snap for users who opt out). Pass `"never"` to always animate the count — e.g. a showcase that must demonstrate it — or `"always"` to force the snap.
`announce`	`boolean`	`false`	Announce the settled value to screen readers via a visually-hidden `aria-live="polite"` sibling. Defaults to `false`. Only the final value (once the tween completes / snaps) is announced — never the ~97 interpolated frames — so opting in stays quiet.