@uekichinos/counter

Lightweight counter animation library that detects and animates all numbers within any string — including integers, decimals, and comma-formatted values.

"We have 1,500,344 customers"  →  counts up from 0 to 1,500,344
"34.67%"                        →  counts up from 0.00% to 34.67%
"RM55 billion"                  →  counts up from RM0 to RM55 billion

• Zero dependencies — plain DOM, no frameworks required
• Any string format — surrounding text is preserved, only numbers animate
• Scroll-triggered or immediate — via Intersection Observer
• Accessibility-aware — respects prefers-reduced-motion
• Works everywhere — ESM, CommonJS, or <script> tag

Installation

npm install @uekichinos/counter

Quick start

Declarative (recommended)

Add data-counter to any element. Call initCounters once.

<p data-counter>RM55 billion</p>
<p data-counter>34.67%</p>
<p data-counter>We have 1,500,344 customers</p>

<script type="module">
  import { initCounters } from '@uekichinos/counter'

  initCounters('[data-counter]')
  // scroll-triggered, animates once, 2s easeOut — all by default
</script>

Programmatic

import { animateCounter } from '@uekichinos/counter'

const el = document.querySelector('#revenue')
animateCounter(el, { duration: 3000, trigger: 'scroll' })

Via <script> tag (no bundler)

<script src="https://unpkg.com/@uekichinos/counter/dist/index.global.js"></script>
<script>
  Counter.initCounters('[data-counter]')
</script>

API

initCounters(selector, options?)

Finds all elements matching selector and animates them. Best for declarative HTML setups.

initCounters('[data-counter]', {
  duration: 2000,
  trigger: 'scroll',
})

Per-element overrides are supported via data attributes:

<p data-counter data-counter-duration="4000" data-counter-trigger="immediate" data-counter-repeat="true">
  99.99%
</p>

| Data attribute | Overrides | |-----------------------------|-----------------| | data-counter-duration | duration | | data-counter-trigger | trigger | | data-counter-repeat | repeat |

animateCounter(el, options?)

Animates a single element.

animateCounter(document.querySelector('#stat'), {
  duration: 2000,
  easing: 'easeOut',
  trigger: 'scroll',
  repeat: false,
  threshold: 0.2,
  startValue: 0,
  onComplete: () => console.log('done'),
})

Options

| Option | Type | Default | Description | |--------------|----------------------------------------|--------------|-------------| | duration | number | 2000 | Animation duration in milliseconds | | easing | 'linear' \| 'easeOut' \| 'easeInOut' | 'easeOut' | Easing function | | trigger | 'scroll' \| 'immediate' | 'scroll' | When to start — on scroll into view, or right away | | repeat | boolean | false | Re-animate each time the element re-enters the viewport | | threshold | number | 0.2 | How much of the element must be visible to trigger (0–1) | | startValue | number | 0 | Value to count up from — useful for live dashboards updating incrementally | | onComplete | () => void | — | Called once when the animation finishes |

Examples

Multiple numbers in one string

All numbers in the string are detected and animate simultaneously.

<p data-counter>
  From 12 offices across 48 countries, we serve 3,200,000 users daily.
</p>

Animate from a previous value

animateCounter(el, { startValue: 1200, duration: 1000 })
// counts from 1,200 → target

Run something after the count finishes

animateCounter(el, {
  onComplete: () => {
    document.querySelector('#badge').classList.add('visible')
  },
})

Repeat on every scroll-in

<p data-counter data-counter-repeat="true">99.99%</p>

Immediate trigger (no scroll)

<p data-counter data-counter-trigger="immediate">1,500,344</p>

Accessibility

If the user has enabled Reduce Motion in their OS settings, all animations are skipped and the final value is displayed immediately. The onComplete callback still fires.

Number formats supported

| Input string | Detected number | |--------------------------------------|-----------------| | RM55 billion | 55 | | RM 55 million | 55 | | 34.67% | 34.67 | | We have 1,500,344 customers | 1500344 | | $1,234.56 total | 1234.56 | | From 12 offices across 48 countries | 12, 48 |

Comma grouping and decimal places are preserved throughout the animation.

License

MIT © uekichinos