Counting Number

Animated counting number with spring transitions and in-view detection. Perfect for React applications requiring smooth number animations with Next.js integration and TypeScript support.

Motion

Loading component...

'use client';import * as React from 'react';import {  type SpringOptions,  type UseInViewOptions,  useInView,  useMotionValue,  useSpring,} from 'motion/react';type CountingNumberProps = React.ComponentProps<'span'> & {  number: number;  fromNumber?: number;  padStart?: boolean;  inView?: boolean;  inViewMargin?: UseInViewOptions['margin'];  inViewOnce?: boolean;  decimalSeparator?: string;  transition?: SpringOptions;  decimalPlaces?: number;};function CountingNumber({  ref,  number,  fromNumber = 0,  padStart = false,  inView = false,  inViewMargin = '0px',  inViewOnce = true,  decimalSeparator = '.',  transition = { stiffness: 90, damping: 50 },  decimalPlaces = 0,  className,  ...props}: CountingNumberProps) {  const localRef = React.useRef<HTMLSpanElement>(null);  React.useImperativeHandle(ref, () => localRef.current as HTMLSpanElement);  const numberStr = number.toString();  const decimals =    typeof decimalPlaces === 'number'      ? decimalPlaces      : numberStr.includes('.')        ? (numberStr.split('.')[1]?.length ?? 0)        : 0;  const motionVal = useMotionValue(fromNumber);  const springVal = useSpring(motionVal, transition);  const inViewResult = useInView(localRef, {    once: inViewOnce,    margin: inViewMargin,  });  const isInView = !inView || inViewResult;  React.useEffect(() => {    if (isInView) motionVal.set(number);  }, [isInView, number, motionVal]);  React.useEffect(() => {    const unsubscribe = springVal.on('change', (latest) => {      if (localRef.current) {        let formatted =          decimals > 0            ? latest.toFixed(decimals)            : Math.round(latest).toString();        if (decimals > 0) {          formatted = formatted.replace('.', decimalSeparator);        }        if (padStart) {          const finalIntLength = Math.floor(Math.abs(number)).toString().length;          const [intPart, fracPart] = formatted.split(decimalSeparator);          const paddedInt = intPart?.padStart(finalIntLength, '0') ?? '';          formatted = fracPart            ? `${paddedInt}${decimalSeparator}${fracPart}`            : paddedInt;        }        localRef.current.textContent = formatted;      }    });    return () => unsubscribe();  }, [springVal, decimals, padStart, number, decimalSeparator]);  const finalIntLength = Math.floor(Math.abs(number)).toString().length;  const initialText = padStart    ? '0'.padStart(finalIntLength, '0') +      (decimals > 0 ? decimalSeparator + '0'.repeat(decimals) : '')    : '0' + (decimals > 0 ? decimalSeparator + '0'.repeat(decimals) : '');  return (    <span      ref={localRef}      data-slot="counting-number"      className={className}      {...props}    >      {initialText}    </span>  );}export { CountingNumber, type CountingNumberProps };

Installation

npx shadcn@latest add https://www.shadcn.io/registry/counting-number.json

npx shadcn@latest add https://www.shadcn.io/registry/counting-number.json

pnpm dlx shadcn@latest add https://www.shadcn.io/registry/counting-number.json

bunx shadcn@latest add https://www.shadcn.io/registry/counting-number.json

Features

Spring animations with customizable stiffness and damping using Motion's useSpring hook
In-view detection triggers animations when component enters viewport with configurable margins
Decimal support with customizable separators and precision control for international formatting
Padding options for consistent width displays with leading zeros and number alignment
TypeScript support with complete interface definitions for all animation and formatting props
Performance optimized using Motion values for smooth 60fps animations without re-renders

Examples

Decimal Numbers

Loading component...

'use client';import * as React from 'react';import {  type SpringOptions,  type UseInViewOptions,  useInView,  useMotionValue,  useSpring,} from 'motion/react';type CountingNumberProps = React.ComponentProps<'span'> & {  number: number;  fromNumber?: number;  padStart?: boolean;  inView?: boolean;  inViewMargin?: UseInViewOptions['margin'];  inViewOnce?: boolean;  decimalSeparator?: string;  transition?: SpringOptions;  decimalPlaces?: number;};function CountingNumber({  ref,  number,  fromNumber = 0,  padStart = false,  inView = false,  inViewMargin = '0px',  inViewOnce = true,  decimalSeparator = '.',  transition = { stiffness: 90, damping: 50 },  decimalPlaces = 0,  className,  ...props}: CountingNumberProps) {  const localRef = React.useRef<HTMLSpanElement>(null);  React.useImperativeHandle(ref, () => localRef.current as HTMLSpanElement);  const numberStr = number.toString();  const decimals =    typeof decimalPlaces === 'number'      ? decimalPlaces      : numberStr.includes('.')        ? (numberStr.split('.')[1]?.length ?? 0)        : 0;  const motionVal = useMotionValue(fromNumber);  const springVal = useSpring(motionVal, transition);  const inViewResult = useInView(localRef, {    once: inViewOnce,    margin: inViewMargin,  });  const isInView = !inView || inViewResult;  React.useEffect(() => {    if (isInView) motionVal.set(number);  }, [isInView, number, motionVal]);  React.useEffect(() => {    const unsubscribe = springVal.on('change', (latest) => {      if (localRef.current) {        let formatted =          decimals > 0            ? latest.toFixed(decimals)            : Math.round(latest).toString();        if (decimals > 0) {          formatted = formatted.replace('.', decimalSeparator);        }        if (padStart) {          const finalIntLength = Math.floor(Math.abs(number)).toString().length;          const [intPart, fracPart] = formatted.split(decimalSeparator);          const paddedInt = intPart?.padStart(finalIntLength, '0') ?? '';          formatted = fracPart            ? `${paddedInt}${decimalSeparator}${fracPart}`            : paddedInt;        }        localRef.current.textContent = formatted;      }    });    return () => unsubscribe();  }, [springVal, decimals, padStart, number, decimalSeparator]);  const finalIntLength = Math.floor(Math.abs(number)).toString().length;  const initialText = padStart    ? '0'.padStart(finalIntLength, '0') +      (decimals > 0 ? decimalSeparator + '0'.repeat(decimals) : '')    : '0' + (decimals > 0 ? decimalSeparator + '0'.repeat(decimals) : '');  return (    <span      ref={localRef}      data-slot="counting-number"      className={className}      {...props}    >      {initialText}    </span>  );}export { CountingNumber, type CountingNumberProps };

Numbers with decimal places and custom separators for international formatting.

From Number Animation

Loading component...

'use client';import * as React from 'react';import {  type SpringOptions,  type UseInViewOptions,  useInView,  useMotionValue,  useSpring,} from 'motion/react';type CountingNumberProps = React.ComponentProps<'span'> & {  number: number;  fromNumber?: number;  padStart?: boolean;  inView?: boolean;  inViewMargin?: UseInViewOptions['margin'];  inViewOnce?: boolean;  decimalSeparator?: string;  transition?: SpringOptions;  decimalPlaces?: number;};function CountingNumber({  ref,  number,  fromNumber = 0,  padStart = false,  inView = false,  inViewMargin = '0px',  inViewOnce = true,  decimalSeparator = '.',  transition = { stiffness: 90, damping: 50 },  decimalPlaces = 0,  className,  ...props}: CountingNumberProps) {  const localRef = React.useRef<HTMLSpanElement>(null);  React.useImperativeHandle(ref, () => localRef.current as HTMLSpanElement);  const numberStr = number.toString();  const decimals =    typeof decimalPlaces === 'number'      ? decimalPlaces      : numberStr.includes('.')        ? (numberStr.split('.')[1]?.length ?? 0)        : 0;  const motionVal = useMotionValue(fromNumber);  const springVal = useSpring(motionVal, transition);  const inViewResult = useInView(localRef, {    once: inViewOnce,    margin: inViewMargin,  });  const isInView = !inView || inViewResult;  React.useEffect(() => {    if (isInView) motionVal.set(number);  }, [isInView, number, motionVal]);  React.useEffect(() => {    const unsubscribe = springVal.on('change', (latest) => {      if (localRef.current) {        let formatted =          decimals > 0            ? latest.toFixed(decimals)            : Math.round(latest).toString();        if (decimals > 0) {          formatted = formatted.replace('.', decimalSeparator);        }        if (padStart) {          const finalIntLength = Math.floor(Math.abs(number)).toString().length;          const [intPart, fracPart] = formatted.split(decimalSeparator);          const paddedInt = intPart?.padStart(finalIntLength, '0') ?? '';          formatted = fracPart            ? `${paddedInt}${decimalSeparator}${fracPart}`            : paddedInt;        }        localRef.current.textContent = formatted;      }    });    return () => unsubscribe();  }, [springVal, decimals, padStart, number, decimalSeparator]);  const finalIntLength = Math.floor(Math.abs(number)).toString().length;  const initialText = padStart    ? '0'.padStart(finalIntLength, '0') +      (decimals > 0 ? decimalSeparator + '0'.repeat(decimals) : '')    : '0' + (decimals > 0 ? decimalSeparator + '0'.repeat(decimals) : '');  return (    <span      ref={localRef}      data-slot="counting-number"      className={className}      {...props}    >      {initialText}    </span>  );}export { CountingNumber, type CountingNumberProps };

Count down from a starting number to demonstrate reverse animations.

Use Cases

This free open source React component works well for:

Statistics dashboards - Animated counters for metrics and KPIs in Next.js applications
Landing pages - Eye-catching number reveals for achievements using TypeScript and Tailwind CSS
Progress indicators - Dynamic counting for completion percentages and user milestones
Financial displays - Currency amounts with proper decimal formatting and animations

API Reference

CountingNumber

Prop	Type	Default	Description
`number`	`number`	required	Target number to count towards
`fromNumber`	`number`	`0`	Starting number for the animation
`decimalPlaces`	`number`	`0`	Number of decimal places to display
`decimalSeparator`	`string`	`"."`	Character used for decimal separation
`padStart`	`boolean`	`false`	Pad with leading zeros to maintain consistent width
`inView`	`boolean`	`false`	Only animate when component enters viewport
`inViewMargin`	`string`	`"0px"`	Margin for in-view detection trigger
`inViewOnce`	`boolean`	`true`	Only trigger in-view animation once
`transition`	`SpringOptions`	`{ stiffness: 90, damping: 50 }`	Motion spring configuration for animation timing
`className`	`string`	-	CSS classes for styling the number display

Animation Configuration

stiffness - Controls animation speed (higher = faster)
damping - Controls bounce/oscillation (higher = less bounce)
mass - Controls animation weight (higher = slower start/stop)

Implementation Notes

Uses Motion's useMotionValue for performance optimization
In-view detection uses Intersection Observer API
Number formatting handles negative values and edge cases
Supports all standard span HTML attributes and events
Animation automatically cleans up on component unmount
Decimal separator replacement works with any Unicode character

Reactcounting-number

Reactcounting-number

Reactcounting-number

On this page