# CountUp.js — Animated Number Counting Library

> A dependency-free JavaScript library that animates a numerical value by counting up or down to a target number with configurable easing, duration, and formatting.

## Install

Save in your project root:

# CountUp.js — Animated Number Counting Library

## Quick Use
```bash
npm install countup.js
```
```js
import { CountUp } from 'countup.js';
const counter = new CountUp('target-el', 5000);
counter.start();
```
```html
<span id="target-el">0</span>
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-326a6e79
Author: AI Open Source