Vanilla JS Library for Smooth Number Transitions – CounterAnime

CounterAnime is a vanilla JavaScript animation library that transforms static numbers into smooth sliding digit counters.

It handles arbitrarily large numbers through BigInt support and creates smooth transitions when values change.

This makes it perfect for scoreboards, real-time dashboards, digital clocks, financial interfaces, statistical counters, and more.

Features:

• Smooth sliding animations for individual digit changes
• BigInt support for handling large numbers beyond JavaScript’s safe integer limit
• Negative number handling with animated minus sign transitions
• Zero-padding configuration for consistent digit display
• Pure vanilla JavaScript with no external dependencies

See It In Action:

How To Use It:

1. Download the package and load the CounterAnime’s files into the document.

<script src="/dist/counterAnime.min.js"></script>
<link rel="stylesheet" href="/dist/style.css" />

2. Instantiate CounterAnime by providing an initial value, a parent DOM element where the counter will be appended, and an optional padding length.

// Assuming you have an HTML element like <div class="my-counter"></div>
const container = document.querySelector(".my-counter");
// Initialize a counter starting at 123, padding to 5 digits (e.g., 00123)
const myCounter = new CounterAnime(123, container, 5);
// If you don't need padding and start at 0:
// const myCounter = new CounterAnime(0, container);

3. API Methods

• setNumber(input): Updates the counter to display a new number value
• increment(): Increases the current value by 1, handles negative number logic
• decrement(): Decreases the current value by 1, automatically shows minus sign when crossing zero
• getElement(): Returns the root DOM element for manual styling or positioning

How It Works

CounterAnime builds a flexible column structure where each digit position contains a vertical stack of numbers 0-9. When a value changes, the library calculates which digits need updating and applies CSS transforms to slide the appropriate number into view.

The architecture uses a wrapper-slide pattern where each digit column has a fixed-width wrapper with hidden overflow, containing a sliding element that moves vertically. This approach provides smooth transitions while maintaining consistent spacing regardless of the displayed number.

BigInt integration happens at the parsing level, where the library converts input values to BigInt internally and formats them as strings for display. This allows handling of numbers beyond JavaScript’s MAX_SAFE_INTEGER limit while maintaining precision for financial applications.

The negative number implementation uses a separate minus sign element that appears and disappears with opacity and width transitions. The library tracks sign state independently from the numeric value, creating smooth transitions when numbers cross zero.

Dynamic digit management adds or removes columns as needed when number length changes. The library recalculates wrapper widths and updates transform values to maintain proper alignment during these structural changes.

FAQs

Q: Can I style the individual digits and animations?
A: Yes, the library provides CSS classes for each component. You can modify .numberAnimation, .numberSlide, and .num classes to change fonts, colors, and spacing. The transition timing and easing functions are also customizable through CSS.

Q: How does CounterAnime handle numbers that change their number of digits (e.g., 99 to 100)?
A: It dynamically adds or removes the necessary digit “slides.” When going from 99 to 100, it will add a new slide for the hundreds place. The numberSlideWrapper‘s width is also adjusted. This is handled by the _updateSlides method, which calls _addSlide or _removeSlide.

Q: Is there a way to animate counting up to a target number?
A: The library handles instant value changes rather than gradual counting. For smooth counting animations, you’d need to implement a timer that calls setNumber() with incremental values until reaching your target.