Guide

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, counter and autoCounter return no-ops and animateNumber jumps to the end.
  • No runtime dependencies.

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>

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.

Stats bandLive preview

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

index.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

style.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

main.js
// 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

index.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>
    <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

index.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

style.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

main.js
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

index.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>
    <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