- Docs
- Getting started
Getting started
Install @samline/counter with a package manager or a script tag and count your first number as it scrolls into view.
Install @samline/counter, then follow the Package / ESM or the HTML / CDN path to the first counter. Both use the same API.
Requirements
- Any modern browser with
Intl.NumberFormat. Without IntersectionObserver, numbers count right away. - On the server,
counterandautoCounterreturn no-ops andanimateNumberjumps to the end. - No runtime dependencies.
Install
npm
npm install @samline/counterpnpm
pnpm add @samline/counteryarn
yarn add @samline/counterbun
bun add @samline/counterHTML / CDN
<script src="https://cdn.jsdelivr.net/npm/@samline/counter@1.14.0/dist/browser/counter.global.js" defer></script>Package / ESM
import { autoCounter } from '@samline/counter'
autoCounter()
<p lang="en">
<span data-counter="12480">12,480</span> customers · <span data-counter="99.95">99.95</span>%
uptime
</p>
autoCounter() counts every [data-counter] in the page, including numbers added later. To count specific elements, call counter(target, options); both return a way to stop. Available as ESM and CommonJS (require('@samline/counter')). There is no stylesheet.
HTML / CDN
For Shopify, WordPress or plain HTML pages without a build step, load the browser bundle. It counts every [data-counter] as soon as the DOM is ready. Pin the version in production.
<script
src="https://cdn.jsdelivr.net/npm/@samline/counter@1.14.0/dist/browser/counter.global.js"
defer
></script>
To pass options, add data-manual to the script tag and start it yourself, or call Counter.auto() from a script that runs before the DOM is ready (a deferred or inline script after the bundle):
<script
src="https://cdn.jsdelivr.net/npm/@samline/counter@1.14.0/dist/browser/counter.global.js"
data-manual
defer
></script>
<script type="module">
Counter.auto({ duration: 1500, locale: 'es-MX' })
</script>
Lite build
Since 1.8.0, @samline/counter/lite counts plain numbers with everything a stats band needs: formatting and the text template, easings, speed, stagger, live values, the controller and the label for screen readers. It leaves out clocks and dates (data-counter-as="time" and "date" stay as rendered), cssVars, output, steady, roll, scramble and announce, counts start: 'scroll' once on visibility, and weighs about 7 KB gzip instead of 10 KB. The API and the attributes are the same, so you can switch either way.
import { autoCounter } from '@samline/counter/lite'
autoCounter()
<script
src="https://cdn.jsdelivr.net/npm/@samline/counter@1.14.0/dist/browser/counter-lite.global.js"
defer
></script>
The lite script also defines window.Counter, so load one of the two bundles, not both.
Working starter files
A complete page you can save and open: the live preview runs the real package, and its files load the published browser bundle.
The HTML holds the final values, so they read correctly without JavaScript. Each number counts once, when half of it is visible, with the decimals of its target.
Scroll down
- Customers
- 12,480
- Uptime
- 99.95%
- Countries
- +42
Explore the code
HTML / CDN
HTML
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Count a stats band when it scrolls in</title>
<link rel="stylesheet" href="./style.css" />
</head>
<body>
<main>
<div id="page">
<p class="spacer">Scroll down</p>
<dl class="stats">
<div>
<dt>Customers</dt>
<dd><span data-counter="12480">12,480</span></dd>
</div>
<div>
<dt>Uptime</dt>
<dd><span data-counter="99.95">99.95</span>%</dd>
</div>
<div>
<dt>Countries</dt>
<dd>+<span data-counter="42">42</span></dd>
</div>
</dl>
</div>
</main>
<script src="https://cdn.jsdelivr.net/npm/@samline/counter@1.14.0/dist/browser/counter.global.js"></script>
<script src="./main.js" defer></script>
</body>
</html>
CSS
#page {
height: 16rem;
overflow-y: auto;
padding: 1rem;
border: 1px solid #ccc;
}
.spacer {
min-height: 20rem;
margin: 0;
}
.stats {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(8rem, 1fr));
gap: 1rem;
margin: 0;
}
dd {
margin: 0;
font-size: 2rem;
font-weight: 600;
font-variant-numeric: tabular-nums;
}
JavaScript
// The box scrolls instead of the page, so pass it as the root.
// Called before the DOM is ready, this replaces the automatic start.
Counter.auto({ root: document.querySelector('#page') })
Complete file
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Count a stats band when it scrolls in</title>
<style>
#page {
height: 16rem;
overflow-y: auto;
padding: 1rem;
border: 1px solid #ccc;
}
.spacer {
min-height: 20rem;
margin: 0;
}
.stats {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(8rem, 1fr));
gap: 1rem;
margin: 0;
}
dd {
margin: 0;
font-size: 2rem;
font-weight: 600;
font-variant-numeric: tabular-nums;
}
</style>
</head>
<body>
<main>
<div id="page">
<p class="spacer">Scroll down</p>
<dl class="stats">
<div>
<dt>Customers</dt>
<dd><span data-counter="12480">12,480</span></dd>
</div>
<div>
<dt>Uptime</dt>
<dd><span data-counter="99.95">99.95</span>%</dd>
</div>
<div>
<dt>Countries</dt>
<dd>+<span data-counter="42">42</span></dd>
</div>
</dl>
</div>
</main>
<script src="https://cdn.jsdelivr.net/npm/@samline/counter@1.14.0/dist/browser/counter.global.js"></script>
<script>
// The box scrolls instead of the page, so pass it as the root.
// Called before the DOM is ready, this replaces the automatic start.
Counter.auto({ root: document.querySelector('#page') })
</script>
</body>
</html>
Package / ESM
HTML
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Count a stats band when it scrolls in</title>
<link rel="stylesheet" href="./style.css" />
</head>
<body>
<main>
<div id="page">
<p class="spacer">Scroll down</p>
<dl class="stats">
<div>
<dt>Customers</dt>
<dd><span data-counter="12480">12,480</span></dd>
</div>
<div>
<dt>Uptime</dt>
<dd><span data-counter="99.95">99.95</span>%</dd>
</div>
<div>
<dt>Countries</dt>
<dd>+<span data-counter="42">42</span></dd>
</div>
</dl>
</div>
</main>
<script type="module" src="./main.js"></script>
</body>
</html>
CSS
#page {
height: 16rem;
overflow-y: auto;
padding: 1rem;
border: 1px solid #ccc;
}
.spacer {
min-height: 20rem;
margin: 0;
}
.stats {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(8rem, 1fr));
gap: 1rem;
margin: 0;
}
dd {
margin: 0;
font-size: 2rem;
font-weight: 600;
font-variant-numeric: tabular-nums;
}
JavaScript
import { autoCounter, counter } from '@samline/counter'
// The box scrolls instead of the page, so pass it as the root.
autoCounter({ root: document.querySelector('#page') })
Complete file
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Count a stats band when it scrolls in</title>
<style>
#page {
height: 16rem;
overflow-y: auto;
padding: 1rem;
border: 1px solid #ccc;
}
.spacer {
min-height: 20rem;
margin: 0;
}
.stats {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(8rem, 1fr));
gap: 1rem;
margin: 0;
}
dd {
margin: 0;
font-size: 2rem;
font-weight: 600;
font-variant-numeric: tabular-nums;
}
</style>
</head>
<body>
<main>
<div id="page">
<p class="spacer">Scroll down</p>
<dl class="stats">
<div>
<dt>Customers</dt>
<dd><span data-counter="12480">12,480</span></dd>
</div>
<div>
<dt>Uptime</dt>
<dd><span data-counter="99.95">99.95</span>%</dd>
</div>
<div>
<dt>Countries</dt>
<dd>+<span data-counter="42">42</span></dd>
</div>
</dl>
</div>
</main>
<script type="module">
import { autoCounter, counter } from '@samline/counter'
// The box scrolls instead of the page, so pass it as the root.
autoCounter({ root: document.querySelector('#page') })
</script>
</body>
</html>
Next steps
Live previews with the complete, copyable source of each one.
API referenceSignatures and behavior of counter, autoCounter, animateNumber, parseNumber and window.Counter.
Attributes, options and states.
Number formattingLocales, currencies, percentages and layout.
Accessibility and motionReduced motion, screen readers and what your page provides.
Framework integrationsReact, Vue, Svelte, Astro and page swaps.