CountUp.js — Animated Number Counting Library

Introduction

CountUp.js animates a numeric value from a start number to an end number with a smooth easing effect. It is commonly used for dashboard statistics, landing page metrics, and progress indicators. The library handles formatting, decimal places, separators, and scroll-triggered start.

What CountUp.js Does

• Animates counting from a start value to an end value with configurable duration
• Supports counting up and counting down with the same API
• Formats numbers with decimal places, thousands separators, and custom prefixes or suffixes
• Provides callbacks for start, complete, and update events
• Pauses, resumes, and resets the animation programmatically

Architecture Overview

CountUp.js uses requestAnimationFrame to update the displayed number on each frame. An easing function (Robert Penner's ease-out expo by default) calculates the current value based on elapsed time. The formatted result is written to the target element's innerHTML or a custom print function. The class instance maintains internal state for pausing, resuming, and resetting without recreating the animation.

Self-Hosting & Configuration

• Install via npm or include the UMD bundle
• Pass the target element ID and end value to the constructor
• Configure startVal, duration, decimalPlaces, separator, and prefix/suffix in the options object
• Set useEasing: false for a linear count instead of ease-out
• Use useGrouping: true (default) to add thousands separators

Key Features

• Tiny library (~3 KB gzipped) with zero dependencies
• Configurable number formatting with locale-aware separators
• Smart easing that decelerates as it approaches the target value
• Scroll-triggered mode using Intersection Observer for on-screen activation
• TypeScript support with full type definitions

Comparison with Similar Tools

• Odometer — flip-counter style with digit rolling; CountUp.js uses inline text with easing
• anime.js — general-purpose animation; CountUp.js specializes in number display
• GSAP TextPlugin — character-by-character text animation; CountUp.js focuses on numeric values
• CSS @property counter — CSS-only approach but limited formatting control; CountUp.js offers full programmatic control

FAQ

Q: Can I start the animation when the element scrolls into view? A: Yes. Set enableScrollSpy: true in the options, and CountUp.js uses Intersection Observer to trigger automatically.

Q: How do I format currency values? A: Set prefix: '$', decimalPlaces: 2, and separator: ',' in the options object.

Q: Can I animate to a new value after the initial count? A: Yes. Call counter.update(newValue) to smoothly transition from the current displayed value to the new target.

Q: Does CountUp.js work with React? A: Yes. Create the instance in a useEffect hook with a ref to the target element. Call start() and clean up with reset() on unmount.

Sources

• https://github.com/inorganik/countUp.js
• https://inorganik.github.io/countUp.js/