- Docs
- Changelog
Changelog
Every @samline/counter release, newest first, with breaking changes, behavior changes and upgrade steps called out explicitly.
All notable changes to this package. Format: Keep a Changelog; versions follow semver.
[1.14.0] - 2026-11-19
Fixed
- Integers past 2^53 end on every digit: a whole final value past
Number.MAX_SAFE_INTEGERindata-counteror in the text is kept as aBigIntand written withIntl.NumberFormat, so18446744073709551615no longer ends as18,446,744,073,709,552,000. Values past 2^53 in between show their own digits instead of 17 digits and zeros. Also in the lite entry.
Added
- Big integers example: 2^64 − 1 in English and Hindi, and wei from a raw attribute.
[1.13.0] - 2026-11-19
Added
data-counter-format:Intl.NumberFormatoptions from HTML as words:compact,percent,scientific,engineering,currency:EUR,unit:kilometer-per-hour,long,narrowandsign, which combine. Theformatoption also takes words or a defined name.defineFormat(name, format), also onwindow.Counterand in the lite entry: nameIntl.NumberFormatoptions or a function that writes the text (clocks and dates too) fordata-counter-formatandformat.parseFormat(words)and theCounterFormattype.- Named formats example: compact downloads, a percentage, euros in German, a speed and file sizes from
defineFormat.
Fixed
- Compact and scientific notation round their own way (
1.5K, not2K) unlessdecimalsis set, and the suffixIntlwrites is no longer kept twice when the HTML already shows it (1.5Kcounted as2KK).
Changed
- Size budgets: 10.5 KB gzip for the main entry and the browser bundle (were 10 KB), 7.5 KB for the lite entry and its bundle (were 7 KB).
[1.12.0] - 2026-11-19
Added
- Ordinals: an English (
st,nd,rd,th) or French (er,e) suffix right after the digits that matches the final value now follows every value, so21stcounts1st,2nd,3rdinstead of2stand3st.ordinaloption anddata-counter-ordinalattribute:trueadds the language’s suffixes, an object ({ one: 'er', other: 'e' }) orone=er other=esets them byIntl.PluralRulesordinal category, andfalsekeeps the suffix as written. Also in the lite entry. ordinal(locale, suffixes),ORDINALSand theOrdinalSuffixestype.- Ordinals example: a rank, a release, a French edition and a Spanish season.
Changed
- Size budgets: 10 KB gzip for the main entry and the browser bundle (were 9.5 KB), 7 KB for the lite entry and its bundle (were 6.5 KB).
[1.11.0] - 2026-11-19
Added
scrambleoption anddata-counter-scrambleattribute: while counting, the element shows the final text with random digits and settles them from left to right, like a code being cracked. Prefixes, separators and suffixes stay, random digits use the script of the text, the digits change every 50 milliseconds, and the count ends on the original markup. Works with numbers, clocks and dates;rollwins where both apply. Main entry only.- Scramble example: an order number, money and a clock that settle digit by digit, with
steady.
[1.10.0] - 2026-11-18
Added
start: 'scroll'anddata-counter-start="scroll": the value follows the scroll position instead of time. A number counts from its start value when its middle enters at the bottom of the viewport (orroot) to its final value at the middle, and back when scrolling up. Easing, events,onUpdate,cssVars,output,rolland live values follow every step. In the lite entry it counts once on visibility.scrollRangeoption anddata-counter-scroll-rangeattribute: where a scroll-linked count starts and ends, as shares of the root height (default[1, 0.5]).- Scroll-linked example: three facts in a scrolling box, with rolling digits and a bar drawn from
--counter-progress.
Changed
- Size budgets: 9.5 KB gzip for the main entry and the browser bundle (were 9 KB), 6.5 KB for the lite entry and its bundle (were 6.25 KB).
[1.9.0] - 2026-11-18
Added
rolloption anddata-counter-rollattribute: each digit is a column that rolls like an odometer while the number counts. A column turnsvalue / 10^placetimes, so every column shows the real digit of its place; columns that turn more than once a frame show whole digits. Prefixes, separators, decimals, suffixes and other scripts’ digits stay in place, digits run left to right in right-to-left text, and the count ends on the original markup. Text whose digits do not follow the value (clocks, dates, compact notation, negative numbers) counts as text. Main entry only.- Rolling digits example: money, a percentage, Arabic-Indic digits and a score with
steady.
Changed
- Size budgets: 9 KB gzip for the main entry and the browser bundle (were 8 KB). The lite entry is unchanged.
[1.8.0] - 2026-11-18
Added
@samline/counter/liteentry anddist/browser/counter-lite.global.js(@samline/counter/browser/lite): the same API for plain numbers, about 6 KB gzip instead of 8 KB. It leaves out clocks and dates (as: 'time'and'date'elements stay as rendered),cssVars,output,steadyandannounce. Both entries sharegetCounterand the owner of each element.
Changed
- Clocks and dates, outputs,
steadyand announcements are separate modules inside the package, so an entry includes only what it uses. The main entry and its behavior are unchanged. - Size budgets: 6.25 KB gzip for the lite entry and bundle; 8 KB for the main ones.
[1.7.0] - 2026-11-18
Added
labeloption anddata-counter-labelattribute, on by default: while the text is not final (waiting, counting or paused), generic elements are exposed as an image labelled with the final value, so screen readers never read a number in between. Elements with a role or label of their own are left alone.announceoption anddata-counter-announceattribute: new values fromset(),increment(),decrement()or a live attribute are read in a shared polite live region once they are shown, as is or through a{value}template.reducedMotionoption anddata-counter-reduced-motionattribute:'count'keeps counting withprefers-reduced-motion: reduce.REDUCED_MOTIONSand theCounterReducedMotiontype.- Screen readers example: the label while counting and visible announcements from two buttons.
Changed
- Waiting and counting numbers carry
role="img"andaria-labeluntil they are done; passlabel: falsefor the previous behavior. - Size budgets: 8 KB gzip for the main entry and the browser bundle (were 7.25 KB).
[1.6.0] - 2026-11-18
Added
steadyoption anddata-counter-steadyattribute: tabular digits and amin-inline-sizereserved for the wider of the start and final text, so the words around a counting number stay still.destroy()restores the original inline styles.- Numbers written in Arabic-Indic, Persian, Devanagari, Bengali, Thai, full-width and other decimal digits are read from the text and count in the same digits.
digitValue()andnumberingSystem()helpers;NumberShapegainszero. format(value, element?)on the controller: the text the counter shows for any value.- Steady layout example: a line with and without
steady, Arabic and Devanagari numbers, and a goal written withformat().
Changed
- Latin digits in the HTML stay Latin in languages whose default digits are others (Arabic, for example), following the rendered text as the template. Pass
format: { numberingSystem }to choose. - Size budgets: 7.25 KB gzip for the main entry and the browser bundle (were 6.5 KB).
[1.5.0] - 2026-11-18
Added
- Easings
ease-in,ease-out-expoandease-out-back. - CSS
cubic-bezier(x1, y1, x2, y2)strings as easings, ineasingand indata-counter-easing.cubicBezier()andisEasing()helpers. speedoption anddata-counter-speedattribute: units per second instead of a fixedduration, so small numbers take less time than big ones; afterset()the time comes from the distance left.staggeroption, anddata-counter-staggeron a container: each next number starts later, also whenautoCountercounts them one by one.- Motion example: seven curves side by side, a staggered row and two speeds.
Changed
- Size budgets: 6.5 KB gzip for the main entry and the browser bundle (were 6 KB).
[1.4.0] - 2026-11-18
Added
outputoption anddata-counter-outputattribute: write the value on screen to<progress>,<meter>and inputs, or asaria-valuenowon other elements, on every frame.outputalso takes a function(value, element, progress).cssVarsoption anddata-counter-css-varsattribute: set--counter-valueand--counter-progress(0to1) on the number, or on its closest ancestor matching a selector.destroy()removes those custom properties and restores the values andaria-valuenowof outputs.CounterOutputtype.- Progress and CSS example: a progress bar, a meter, a ring and a goal bar.
Changed
- Size budgets: 6 KB gzip for the main entry and the browser bundle (were 5.6 KB).
[1.3.0] - 2026-11-18
Added
- Live numbers: the controller’s
set(value),increment(by)anddecrement(by)count from the value on screen to a new final value, for one element or all of them. Quickincrementcalls add up. - Changing
data-counter(ordatetimewithas: 'date') counts to the new value on its own; turn it off withlive: falseordata-counter-live="false". animateNumberreturns its cancel function withpause(),resume(),retarget(to, duration?),getValue()andisRunning(). TheNumberAnimationtype describes it.- Live numbers example: a monthly or yearly price, a cart with add and remove buttons, and visitors updated through the attribute.
Changed
getSnapshot()keepsprogressbetween0and1after a new value.- Size budgets: 5.6 KB gzip for the main entry and the browser bundle (were 5.3 KB).
[1.2.0] - 2026-11-18
Added
asoption anddata-counter-asattribute.'time'counts seconds in the pattern of the text (23:59:59or90:00), carrying seconds into minutes and hours;data-counter-fromaccepts a clock.'date'counts day by day up to thedatetime(or an ISO date indata-counter), from January 1 of that year ordata-counter-from, formatted withIntl.DateTimeFormat(data-counter-date-styleordateFormat), and ends on the rendered text.stepoption anddata-counter-stepattribute: show whole steps only, in units, seconds or days; the final value stays exact.readClock,writeClockandreadDatehelpers;CounterKindandClockShapetypes.- Clock and calendar example. The Controls example uses
as: 'time'instead of a formatter.
Changed
- Size budgets: 5.3 KB gzip for the main entry and the browser bundle (were 4.4 and 4.45 KB).
[1.1.0] - 2026-11-18
Added
counter()returns a controller withstart(),pause(),resume(),reset(),finish(),update(options),refresh(),getSnapshot()andon(event, listener). Commands act on every element or on one, and chain. The controller is still callable as the cleanup, so 1.0 code keeps working.startoption anddata-counter-startattribute:'visible'(default),'load'or'manual'.groupingoption anddata-counter-groupingattribute:'auto'(default) writes digits the way the HTML does,truegroups as the language does (a raw8000from a backend counts to8,000),falsenever groups.- Formats example: grouping, decimals and text around the number, with a Count again button.
pausedstate indata-counter-state.- Bubbling DOM events
counter:start,counter:pause,counter:resume,counter:resetandcounter:complete, with{ element, value, state }asdetail. getCounter(element), also onwindow.Counter, returns the controller counting an element.readShape(text, locale?)and the controller types (CounterController,CounterEvent,CounterEventDetail,CounterListener,CounterSnapshot,CounterStart,NumberShape).- Controls example: a simulated clock started, paused and finished from buttons.
Fixed
- Counting keeps the text around the number:
$8,000no longer loses its$, and8.000,45 €keeps its€. It also stays withformat, unlessformat.styleiscurrency,percentorunit. - When the final value reads like the original text, the count ends on the original markup, so
100<sup>+</sup>is shown as written once done, not only afterdestroy().
Changed
- Digits count the way the HTML writes them:
8000now counts to8000(1.0 showed8,000). Setgrouping: trueordata-counter-grouping="true"for the separators of the language. - Calling
counter()for elements another controller already counts leaves them to it, and returns that controller when it owns them all. Before, a second call counted the same element twice. - Size budgets: 4.4 KB gzip for the main entry, 4.45 KB for the browser bundle (were 3.1 and 3.2 KB).
[1.0.1] - 2026-11-17
Fixed
- Cleanup restores the element’s original child nodes instead of only its text, so markup inside a counter (for example
100<sup>+</sup>) survivesdestroy()and removal.
Changed
- Internal: the DOM controller moved from
src/coretosrc/vanilla;src/corekeeps the DOM-free types, constants and helpers. Public entries are unchanged. - The package moved from the
samline/utilsmonorepo to its own repository, samline/counter. Homepage, repository and documentation links point to the package’s own site.
[1.0.0] - 2026-11-13
Added
- First release:
counterandautoCountercount numbers as they scroll into view, from the final value rendered in the HTML, with time-based easing, decimals taken from the target,Intl.NumberFormatformatting in the element’s language (currencies, compact, units or your ownformatter), counting down,repeatand reduced-motion support.animateNumbertweens any number andparseNumberreads localized text. ESM, CommonJS and a browser global (window.Counter) that starts on its own.