- Docs
- Configuration options
Configuration options
Every @samline/counter attribute, JavaScript option and state, with defaults and which one wins.
Attributes
Attributes win over options, so one call can set defaults and each number can override them.
| Attribute | Value | Description |
|---|---|---|
data-counter |
number, or empty | The final value as a plain number (12480, 99.95, -3). Empty reads it from the text. |
data-counter-from |
number | Start value. Higher than the target counts down. |
data-counter-duration |
milliseconds | How long counting takes |
data-counter-delay |
milliseconds | Wait before counting |
data-counter-speed |
units per second | Count at a steady rate instead of a fixed duration (since 1.5.0) |
data-counter-stagger |
milliseconds, on a container | Each next [data-counter] inside starts this much later (since 1.5.0) |
data-counter-easing |
an easing name or cubic-bezier() |
Curve of the count: linear, ease-in, ease-out, ease-in-out, ease-out-expo, ease-out-back or cubic-bezier(x1, y1, x2, y2) |
data-counter-decimals |
number | Decimals to show |
data-counter-locale |
BCP 47 tag | Language for formatting and for reading the text |
data-counter-repeat |
present, or false |
Reset on leaving, count again on every entry |
data-counter-start |
visible, load, manual, scroll |
When counting starts (since 1.1.0); scroll follows the scroll position (since 1.10.0) |
data-counter-scroll-range |
two numbers, such as 1 0.5 |
With start: 'scroll', where the count starts and ends, as shares of the viewport or root height from the top (since 1.10.0) |
data-counter-live |
present, or false |
Count to a new data-counter or datetime when it changes; on by default (since 1.3.0) |
data-counter-css-vars |
present, false, or a selector |
Set --counter-value and --counter-progress on the number or its closest match (1.4.0) |
data-counter-output |
selector | Write the value to a <progress>, <meter>, input or aria-valuenow (since 1.4.0) |
data-counter-steady |
present, or false |
Tabular digits and the width of the wider of the start and final text reserved, so nothing moves (since 1.6.0) |
data-counter-roll |
present, or false |
Roll each digit like an odometer while counting; numbers only, not in the lite entry (since 1.9.0) |
data-counter-scramble |
present, or false |
Show random digits in the shape of the final text and settle them from left to right; not in the lite entry (since 1.11.0) |
data-counter-label |
present, or false |
Expose the final value to screen readers while the text is not final; on by default (since 1.7.0) |
data-counter-announce |
present, false, or a template |
Announce new values in a polite live region; {value} is the final text (since 1.7.0) |
data-counter-reduced-motion |
final, count |
With reduced motion, show the final value (default) or count anyway (since 1.7.0) |
data-counter-format |
words such as compact, percent, currency:EUR, or a defined name |
Intl.NumberFormat options from HTML, or a format named with defineFormat (since 1.13.0) |
data-counter-grouping |
auto, true, false |
Group separators: as the HTML writes them, as the language does, or never (since 1.1.0) |
data-counter-ordinal |
present, false, or suffixes such as one=er other=e |
Ordinal suffixes that follow the value; English and French are recognized by default (since 1.12.0) |
data-counter-as |
number, time, date |
What the number means: a number, seconds shown as a clock, or days between dates (1.2.0) |
data-counter-step |
number | Show whole steps only: units, seconds with time, days with date (since 1.2.0) |
data-counter-date-style |
full, long, medium, short |
Date format with as="date"; default long (since 1.2.0) |
datetime |
ISO date | Final date with as="date"; data-counter-from takes an ISO date too |
Options
| Option | Default | Description |
|---|---|---|
from |
0 |
Start value |
to |
— | Final value when data-counter has no number; by default it is read from the text |
duration |
2000 |
Milliseconds |
delay |
0 |
Milliseconds before counting |
speed |
— | Units per second instead of duration; seconds with time, days with date |
stagger |
0 |
Milliseconds added to the delay of each next element of the call |
easing |
'ease-out' |
A name, a cubic-bezier() string, or a function from progress (0–1) to eased progress |
decimals |
from the target | Decimals to show |
locale |
closest lang |
BCP 47 locale; an invalid one falls back to the browser’s |
format |
— | Intl.NumberFormat options, for example { style: 'currency', currency: 'EUR' }; or a defined name or words, as in data-counter-format |
formatter(value, element) |
— | Returns the text yourself; replaces locale, decimals and format |
repeat |
false |
Count again every time the number enters |
start |
'visible' |
'visible', 'load' (right away), 'manual' (when you call start()) or 'scroll' |
scrollRange |
[1, 0.5] |
With start: 'scroll', where the count starts and ends, as shares of the root height |
live |
true |
Count to a new data-counter or datetime when it changes |
cssVars |
false |
true, or a selector for the closest ancestor, such as '.card' |
output |
— | A selector, element or list to write the value to, or (value, element, progress) => void |
steady |
false |
Tabular digits and a reserved width while counting, so the layout keeps still |
roll |
false |
Each digit rolls like an odometer while counting; numbers only |
scramble |
false |
Random digits that settle from left to right while counting |
label |
true |
The final value as the label of generic elements while the text is not final |
announce |
false |
true, or a template such as '{value} people online', to announce new values |
reducedMotion |
'final' |
'count' counts even with prefers-reduced-motion: reduce |
grouping |
'auto' |
'auto' copies the HTML, true groups as the language does, false never groups |
ordinal |
recognized in English and French | true, false, or suffixes by plural category: { one: 'er', other: 'e' } |
as |
'number' |
'time' (seconds as a clock) or 'date' (days between two dates) |
step |
none; 1 with time and date |
Whole steps only, in the unit of the value; the final value is always exact |
dateFormat |
{ dateStyle: 'long' } |
Intl.DateTimeFormat options with as: 'date' |
root |
viewport | Scroll container to observe against |
rootMargin |
'0px' |
Grows or shrinks the root |
threshold |
0.5 |
Share of the number that must be visible to start |
onStart(element) |
— | Counting starts |
onUpdate(value, element) |
— | Every frame, with the unformatted value |
onComplete(element) |
— | The final value is shown (also right away with reduced motion) |
selector, scope, observe |
'[data-counter]', document, true |
autoCounter only |
Easing, speed and stagger
Since 1.5.0:
- Easings:
linear,ease-in,ease-out(default),ease-in-out,ease-out-expo(fast start, long landing, good for big numbers) andease-out-back(goes a little past the target, then settles). Any CSScubic-bezier(x1, y1, x2, y2)works too, also indata-counter-easing;x1andx2must be between0and1, and an invalid curve falls back toease-out. - Speed:
data-counter-speed="1000"counts 1,000 units per second, so500takes half a second and4000four seconds; it replacesduration. Afterset(), the time comes from the distance left. Seconds per second withas="time", days per second withas="date". - Stagger:
data-counter-stagger="150"on a container starts its[data-counter]elements 150 ms apart, in document order, also whenautoCountercounts them one by one. In JavaScript,staggerdoes the same for the elements of onecounter()call. It adds todelay, and only the first count of each element waits.
<p data-counter-stagger="150">
<span data-counter="120">120</span>
<span data-counter="340">340</span>
<span data-counter="560">560</span>
</p>
<span data-counter="1000" data-counter-easing="cubic-bezier(0.2, 0.8, 0.2, 1)">1000</span>
The Motion example shows every curve side by side.
Steady layout and digits
Since 1.6.0:
- Steady:
data-counter-steadysetsfont-variant-numeric: tabular-numsand amin-inline-size(inem, so it follows the font size) equal to the wider of the start and final text, and turns inline text into an inline block. The words after a growing number stay where they are, and the alignment of the parent still applies inside the box. It measures again for each new value fromset()or a live attribute, changes nothing with reduced motion, anddestroy()puts the original inline styles back. - Digits in any script: text written in Arabic-Indic (
١٬٢٣٤), Persian, Devanagari (१,२३४), Bengali, Thai, full-width or other decimal digits is read as a number and counts in the same digits. Latin digits stay Latin, also in a language that writes others by default.format: { numberingSystem: 'arab' }chooses the digits yourself.
<p><span data-counter data-counter-steady>1,250,000</span> downloads this year</p>
<p lang="ar" dir="rtl"><span data-counter>١٬٢٥٠٬٠٠٠</span> تنزيل</p>
The Steady layout example shows the difference side by side.
Scroll-linked counting
Since 1.10.0, data-counter-start="scroll" (or start: 'scroll') ties the value to the scroll position instead of time: the number starts counting when its middle enters at the bottom of the viewport, reaches its final value when it gets to the middle, and counts back when you scroll up.
data-counter-scroll-range="1 0.5"(orscrollRange: [1, 0.5]) sets where the count starts and ends, as shares of the viewport height from the top:1is the bottom edge,0.5the middle,0the top."0.9 0.3"counts over a longer stretch of the scroll.- Inside a scrolling box, pass it as
root, as for visibility:autoCounter({ root: document.querySelector('#story') }). - The easing shapes the count along the scroll;
duration,delay,speed,staggerandrepeatdo not apply. Events,onUpdate,cssVars,outputandrollfollow every step, and a live value changes at the same place of the scroll. - With reduced motion, the number keeps its final value, as always;
data-counter-reduced-motion="count"follows the scroll anyway. - In
@samline/counter/lite,scrollcounts once on visibility, likevisible.
<span data-counter="384400" data-counter-start="scroll">384,400</span> km to the Moon
The Scroll-linked example counts three facts in a scrolling box, with rolling digits and a bar drawn from --counter-progress.
Rolling digits
Since 1.9.0, data-counter-roll (or roll: true) turns each digit into a column that rolls while the number counts, like an odometer. A column turns value / 10^place times, so the last digit spins fastest and every column always shows the real digit of its place; a column that turns more than once a frame shows whole digits. The prefix, separators, decimals and suffix stay in place, Arabic-Indic and other digits roll in their own script, and the digits always run left to right, also in a right-to-left paragraph.
- Leading places appear as the number grows; with
data-counter-steadythey keep their width from the start. - It needs text whose digits are exactly the value (
1,250,$12.50,99.95%). Clocks, dates, compact notation (8K) and negative numbers count as text. - The count ends on the original markup, and the columns are hidden from screen readers, which get the final value.
- It uses inline styles, so there is no stylesheet. It is in the main entry, not in
@samline/counter/lite.
<span data-counter="1250000" data-counter-roll>$1,250,000</span>
The Rolling digits example shows money, a percentage, Arabic-Indic digits and a score.
Scrambled digits
Since 1.11.0, data-counter-scramble (or scramble: true) shows the final text with random digits while the number counts, and settles them from left to right as the count goes on, like a code being cracked. When the count ends, the original markup is back.
- The prefix, separators, decimals and suffix stay in place, and random digits are drawn in the script of the text, so
١٬٢٥٠scrambles in Arabic-Indic digits. - It works with numbers, clocks and dates. Easing and
speedset how fast the digits settle; withstart: 'scroll', they follow the scroll. - While waiting, the number shows its start value. The random digits change every 50 milliseconds, not every frame.
- The text jumps to the width of the final value when scrambling starts; add
data-counter-steadyto reserve that width from the start. - Screen readers get the final value, as with any count. Where
rollalso applies, it wins. It is in the main entry, not in@samline/counter/lite.
<span data-counter="1250000" data-counter-scramble data-counter-steady>$1,250,000</span>
The Scramble example decodes an order number, money and a clock.
Units of from and to
With as: 'time', from and to are seconds (data-counter-from also accepts a clock such as 08:00:00). With as: 'date', they are timestamps in milliseconds; from defaults to January 1 of the final date’s year. onUpdate, listeners and getSnapshot() report values in the same unit, already rounded to the step.
Final value and decimals
The final value comes from the first of these that holds a number:
data-counter="1234.5", a plain number with a.for decimals;- the
tooption; - the element’s text, read in its language:
1.234,5in German,$1,234.50in English.
The rendered text is the template
A number counts the way the HTML writes it (since 1.1.0):
- Grouping follows the text with
grouping: 'auto'(the default):8000counts to8000and8,000to8,000.trueadds the separators of the language (8000→8,000in English,8.000in German);falseremoves them. With fewer than four digits in the text there is nothing to copy, so'auto'groups as the language does.format.useGroupingwins overgrouping. - Text around the number stays:
$8,000counts as$0,$1,250…$8,000, and8.000,45 €keeps its€. It also stays withformat, unlessformat.styleiscurrency,percentorunit, which add their own symbols.formatterreplaces the whole text. - Markup comes back at the end when the final value reads exactly like the original text, so
100<sup>+</sup>ends as written. When it reads differently (for example8000withgrouping: true), the count ends on the formatted value.
| HTML | Options | Ends as |
|---|---|---|
8000 |
— | 8000 |
8,000.45 |
— | 8,000.45 |
8000 |
grouping: true |
8,000 |
$8000 |
grouping: true |
$8,000 |
8000 + data-counter-decimals="2" |
grouping: true |
8,000.00 |
8,000 |
grouping: false |
8000 |
8000,5 in lang="de" |
grouping: true |
8.000,5 |
8000 visits |
format: { notation: 'compact' } |
8K visits |
8000 |
grouping: true, format: { style: 'currency', currency: 'USD' } |
$8,000 |
The Formats example runs every row.
Decimals come from how the target is written: data-counter="12.50" shows two decimals all the way. With format: { style: 'percent' }, write fractions (0.25 for 25%); two decimals are taken off for the percentage.
States
The script sets data-counter-state on each number:
| State | Meaning |
|---|---|
pending |
Showing the start value, waiting to start |
counting |
Counting |
paused |
Stopped by pause(), waiting for resume() |
done |
Showing the final value |
Use them in CSS, for example to highlight a number while it counts:
[data-counter-state='counting'] {
color: var(--accent);
}