- Docs
- API reference
API reference
Every @samline/counter export, counter, autoCounter, animateNumber, parseNumber, EASINGS and the window.Counter browser global.
counter(target?, options?)
counter(target?: ElementTarget, options?: CounterOptions): CounterController
Counts target when it scrolls into view and returns a controller. target is a selector, an element, a NodeList or an array, and defaults to '[data-counter]'. Elements without a final value (no number in data-counter, no to option and no number in the text) are left alone.
import { counter } from '@samline/counter'
const stats = counter('.stat', { duration: 1500, easing: 'ease-in-out' })
// Later: stop counting and put the original markup back.
stats.destroy() // or stats()
The controller is also a function: calling it is the same as destroy(), so code written for 1.0 (const stop = counter(); stop()) keeps working. destroy() cancels any running count, restores each element’s original markup and removes data-counter-state. Calling it twice is safe. On the server, or with no matching elements, counter returns a controller whose methods do nothing.
An element is counted by one controller at a time. Calling counter again for elements another controller already counts leaves them to it; when every element belongs to one controller, that controller is returned.
The controller
Since 1.1.0. Commands act on every element of the controller, or only on element when you pass one, and return the controller so they can be chained. After destroy() they do nothing.
| Member | Description |
|---|---|
elements |
The elements this controller counts |
set(value, element?) |
Count from the value on screen to value, which becomes the final value (since 1.3.0) |
increment(by?, element?) |
Add by (default 1) to the final value and count to it; quick calls add up (since 1.3.0) |
decrement(by?, element?) |
Subtract by (default 1) from the final value and count to it (since 1.3.0) |
start(element?) |
Count from the start value now, even if the element is not visible yet |
pause(element?) |
Pause a running count; paused time does not count |
resume(element?) |
Continue a paused count |
reset(element?) |
Stop and show the start value; call start() to count again |
finish(element?) |
Jump to the final value |
update(options) |
Merge options (attributes still win). Waiting elements show the new start, running ones count again |
refresh() |
Read the data-counter-* attributes again |
getSnapshot() |
One { element, value, state, from, to, progress } per element; progress goes from 0 to 1 |
format(value, element?) |
The text the counter shows for value, with the element’s template, clock or date style (since 1.6.0) |
on(event, listener) |
Listen to start, update, pause, resume, reset or complete; returns a function that stops listening |
destroy() |
Stop and restore the original markup |
const total = counter('#total', { start: 'manual', duration: 1200 })
total.on('complete', ({ element, value }) => console.log(element.id, value))
document.querySelector('#play').addEventListener('click', () => total.start())
document.querySelector('#hold').addEventListener('click', () => total.pause())
Listeners receive { element, value, state }, where value is the number on screen. update runs on every frame.
Live numbers
Since 1.3.0, a number can change after it counts. set(), increment() and decrement() count from the value on screen to the new one, with the element’s duration and easing and no delay; each new value is a new start, and its complete follows. A number still waiting to start counts to the new value when it starts. With reduced motion the new value shows at once. Since 1.7.0, announce reads each new value in a polite live region once it is shown; see Accessibility.
const price = counter('#price')
document.querySelector('#yearly').addEventListener('click', () => price.set(10))
const items = counter('#items')
document.querySelector('#add').addEventListener('click', () => items.increment())
Changing data-counter (or datetime with as: 'date') does the same, so a server, htmx swap or framework that only updates the attribute gets a counting number for free. New decimals come from the new value. Turn it off per element with data-counter-live="false", or for a call with live: false.
// Somewhere your data arrives:
visitors.dataset.counter = String(latest)
DOM events
Every event except update is also dispatched on the element as a bubbling CustomEvent named counter:start, counter:pause, counter:resume, counter:reset or counter:complete, with the same detail. They work without a reference to the controller, for example on pages that use the browser bundle:
document.addEventListener('counter:complete', event => {
event.target.classList.add('is-done')
})
getCounter(element)
getCounter(element: Element | null | undefined): CounterController | null
Returns the controller counting element, or null. Use it to control numbers that autoCounter or the browser bundle started:
getCounter(document.querySelector('#hero-number'))?.start()
autoCounter(options?)
autoCounter(options?: AutoCounterOptions): { refresh(): void; destroy(): void }
Counts every element matching selector (default '[data-counter]') inside scope (default document). With observe: true (the default) it also counts matching elements added later and cleans up elements that are removed.
AutoCounterOptions accepts every CounterOptions field plus selector, scope and observe.
animateNumber(options)
animateNumber(options: AnimateNumberOptions): () => void
The eased tween behind counter, for anything that is not text: charts, canvas, CSS variables. Returns a function that cancels it.
import { animateNumber } from '@samline/counter'
const cancel = animateNumber({
from: 0,
to: 72,
duration: 800, // ms, default 2000
delay: 0,
easing: 'ease-out', // any EASINGS name, 'cubic-bezier(…)' or (progress) => eased
onUpdate: value => gauge.style.setProperty('--value', value),
onComplete: () => console.log('done'),
})
It is time-based, so it lasts the same at any frame rate. onUpdate receives to exactly on the last call; onComplete is not called when cancelled. Without requestAnimationFrame, or with duration: 0, it jumps to to at once.
Since 1.3.0 the returned function also has controls; calling it still cancels:
| Member | Description |
|---|---|
cancel() |
Stop for good; same as calling the function |
pause() / resume() |
Stop and continue; time spent paused does not count |
retarget(to, duration?) |
Count from the current value to to, also after it finished; onComplete runs again |
getValue() |
The last value sent to onUpdate |
isRunning() |
Whether it is counting right now |
const gauge = animateNumber({ to: 40, onUpdate: v => meter.style.setProperty('--value', v) })
socket.addEventListener('message', event => gauge.retarget(Number(event.data), 600))
parseNumber(text, locale?)
parseNumber(text: string, locale?: string): { value: number; decimals: number } | null
Reads a number written for people in locale: parseNumber('1.234,5 €', 'de') returns { value: 1234.5, decimals: 1 }. Grouping, currency symbols and spaces are ignored; a leading - or − makes it negative. Returns null when there is no digit. counter uses it when data-counter is empty. Since 1.6.0 it reads decimal digits in any script: parseNumber('١٬٢٣٤٫٥', 'ar') returns { value: 1234.5, decimals: 1 }.
digitValue(char) returns the value of one digit in any script ('٧' and '७' are 7), or -1. numberingSystem(zero) returns the Intl numbering system whose zero is zero ('٠' is 'arab'), or undefined when the browser cannot tell.
Since 1.12.0, ordinal(locale, suffixes) returns a function that gives the ordinal suffix of the whole number nearest to a value: ordinal('en', ORDINALS.en)(22) is 'nd'. ORDINALS holds the suffixes counter recognizes (en and fr), typed as OrdinalSuffixes: suffixes by Intl.PluralRules ordinal category.
defineFormat(name, format)
defineFormat(name: string, format: Intl.NumberFormatOptions | ((value: number, element: Element) => string)): void
Since 1.13.0. Names a format for data-counter-format="name" and format: 'name': Intl.NumberFormat options, or a function that writes the text (for clocks and dates too). Elements read after the call use it; a name defined again replaces it. Both entries share the names. parseFormat(words) returns the Intl.NumberFormat options that words such as 'compact currency:USD' stand for, and CounterFormat is the type of a named format. The formatting guide lists the words.
EASINGS
import { EASINGS } from '@samline/counter'
// { linear, 'ease-in', 'ease-out', 'ease-in-out', 'ease-out-expo', 'ease-out-back' }
// Functions from progress (0–1) to eased progress.
Since 1.5.0, cubicBezier('cubic-bezier(0.2, 0.8, 0.2, 1)') returns the CSS curve as a function (or null when the string is not a valid curve), and isEasing(value) tells whether a value is an easing name, a valid cubic-bezier() or a function.
Easing, EasingName, CounterState, CounterStart, CounterOptions, AutoCounterOptions, AnimateNumberOptions, CounterController, CounterEvent, CounterEventDetail, CounterListener, CounterSnapshot and NumberShape are exported as types. readShape(text, locale?) reports the prefix, suffix, grouping and, since 1.6.0, the zero of the digits of a rendered number, which counter uses as the template. Since 1.2.0, readClock(text) reads a clock ('23:59:59' → 86399 seconds, with its pattern), writeClock(seconds, fields, padded, digits) writes one, and readDate(value) reads an ISO date or timestamp; CounterKind, ClockShape and NumberAnimation are exported as types. Since 1.7.0, REDUCED_MOTIONS lists the values of reducedMotion, typed as CounterReducedMotion. @samline/counter/vanilla exports counter as its default export.
@samline/counter/lite
Since 1.8.0. The same counter, autoCounter, getCounter, defineFormat, animateNumber, parseNumber, EASINGS, cubicBezier and isEasing, for plain numbers only. Elements with data-counter-as="time" or "date" are not counted and keep their text; cssVars, output, steady, roll, scramble and announce (options and attributes) are ignored, and start: 'scroll' counts once on visibility. counter is also the default export. Both entries share getCounter and one owner per element, so an element counted by one is left alone by the other. The browser build is dist/browser/counter-lite.global.js (@samline/counter/browser/lite) and defines the same window.Counter.
window.Counter
The browser bundle (dist/browser/counter.global.js) defines window.Counter and counts every [data-counter] as soon as the DOM is ready.
| Member | Description |
|---|---|
Counter.counter(target, options) |
Same as counter |
Counter.autoCounter(options) |
Same as autoCounter |
Counter.animateNumber(options) |
Same as animateNumber |
Counter.getCounter(element) |
Same as getCounter |
Counter.defineFormat(name, format) |
Same as defineFormat (since 1.13.0) |
Counter.auto(options) |
Starts, or restarts, the automatic run with options and returns its controller |
Counter.controller |
The controller of the automatic run, or null |
Add data-manual to the script tag to skip the automatic start. Calling Counter.auto() before the DOM is ready also replaces it, so a deferred or inline script after the bundle can pass its own options. To count elements with different options, give them a class instead of data-counter and call Counter.counter('.price', options), so the automatic run does not count them too.