Count up. Keep the number.

Counter
Numbers that land on the truth.

Add data-counter to a number and it counts up when it scrolls into view, formatted for the language of the page.
Install it, watch the live preview, then read the full reference.

npm install @samline/counter

From 7 KB gzipZero dependenciesMIT licensed

Counter previewLive preview
Downloads
12,480
Uptime
98.6%
Rating
4.9 / 5
Cities
+1,200

ONE SMALL SCRIPT. RIGHT AT HOME IN YOUR STACK.

JavaScript TypeScript React Vue Svelte Shopify WordPress
01 / More than a loop

The real value first.
The animation second.

Final value in the HTML

You render 12,480; the script counts to it. Search engines, screen readers and visitors without JavaScript always get the real number.

Reduced motion respected

With prefers-reduced-motion, numbers never move: the rendered value stays, and turning it on mid-count jumps to the end.

Formatted for the language

Intl.NumberFormat with the closest lang attribute: 1.234,5 in German, 12,34,567 in India, currencies and compact notation.

Decimals that make sense

data-counter="99.95" counts with two decimals all the way; a target written with no decimals counts in whole numbers.

Time-based easing

Counts by elapsed time, not frames, so it lasts the same on every screen, with ease-out, ease-in-out, linear or your own curve.

Up, down, or again

Start from any value to count down, and data-counter-repeat counts again every time the number comes back.

02 / Fit it into your stack

Attributes first. Script when you need it.

Configure with attributes or options; animateNumber works without the DOM.

Package

@samline/counter

counter, autoCounter and animateNumber as ESM or CommonJS.

Elements

counter(target, options)

Count a selector, element or list; returns a cleanup.

Whole page

autoCounter(options)

Every [data-counter], including content added later.

HTML / CDN

window.Counter

A classic script that starts on its own.

Any number

animateNumber(options)

The eased tween behind it, for charts, canvas or your own UI.

Parsing

parseNumber(text, locale)

Read 1.234,5 or $1,234.50 back into a number.

03 / Install and count

One attribute. One call.

Count a statistic up when it scrolls into view.

Read the installation guide
1

Install

npm

Terminal
npm install @samline/counter

pnpm

Terminal
pnpm add @samline/counter

yarn

Terminal
yarn add @samline/counter

bun

Terminal
bun add @samline/counter

HTML / CDN

Terminal
<script src="https://cdn.jsdelivr.net/npm/@samline/counter@1.14.0/dist/browser/counter.global.js" defer></script>
2

Mark the number

Render the final value and put the plain number in data-counter.

index.html
<p>
  <span data-counter="12480">12,480</span> customers
</p>

Continue with every attribute, option and formatting choice.

Explore the options
04 / Beyond counting up

Formats in options.
Timing in attributes.

Three common jobs, without writing an animation loop.

format

Prices in any currency

Pass Intl.NumberFormat options to every number.

Read the options
main.js
counter('.price', {
  locale: 'es-MX',
  format: { style: 'currency', currency: 'MXN' },
})
data-counter-from

Count down

Start above the target and it counts down.

Read the options
index.html
<span data-counter="0" data-counter-from="10" data-counter-easing="linear">0</span>
animateNumber

Animate a chart value

The same easing for anything that is not text.

Read the API
main.js
animateNumber({
  to: 72,
  duration: 800,
  onUpdate: value => gauge.style.setProperty('--value', value),
})
Explore working examples
05 / Before you build

A few details. Clearly answered.

Why render the final value in the HTML?
So the number is right for search engines, link previews, screen readers and visitors without JavaScript. The script replaces it with the start value only when it is about to animate.
Does it work without a bundler?
Yes. Load dist/browser/counter.global.js; it counts every [data-counter] on its own. Add data-manual to the script tag to start it yourself with Counter.auto(). Pin the version in production.
Can it count currencies, percentages or compact numbers?
Yes. Pass Intl.NumberFormat options as format, such as { style: 'currency', currency: 'EUR' } or { notation: 'compact' }; every frame is formatted the same way. For full control, formatter(value, element) returns the text yourself.
Where do units, + and % go?
Outside the counted element: +<span data-counter="42">42</span>%. For currencies and percentages formatted by Intl, use the format option instead.
How do I stop the text from jumping?
Use font-variant-numeric: tabular-nums so every digit has the same width, and give the number an inline-block min-width if it shares a line with other text.
When does counting start?
When half of the number is visible (threshold 0.5), in the viewport or in the scroll container you pass as root. Numbers already visible on load start right away.
How are decimals decided?
From the target: data-counter="99.95" shows two decimals throughout. Set data-counter-decimals or the decimals option to change it.
Does it see numbers added later?
autoCounter and the CDN script watch the page, so numbers added by AJAX, infinite scroll or page swaps count too, and removed ones are released.
Numbers, counted right

Count up, land on the truth.

Try the examples or follow the first steps.

Guides, the complete API and release notes, in one place.

Read the documentation