react-strp-counter

A high-performance, CSS-only animated counter for React that never re-renders on value updates.

Ideal for dashboards, KPIs, and animated counters where performance and visual smoothness matter.

LIGHT Package Size:

Demo: https://stripearmy.github.io/strp-counter-demo/

✨ Features

⚡ Zero re-renders — DOM is fully static after mount
🔁 2 modes:
- Static: Only changed digits animate
- Rolling: Seamless jackpot-style rolling using duplicated digit strings
🧩 Accepts numbers or formatted strings
🏷 Optional unit label with positioning
🧠 Ripple-style animation with dynamic delay per digit

How It Works

This component avoids React re-renders by offloading all animation logic to CSS variables and direct DOM manipulation. Every digit is pre-rendered via CSS content (:before) and animated with transform.

In rolling mode, digits animate smoothly from their current index to index + 10 (which wraps visually), and snap back after the transition ends.

📦 Installation

npm install react-strp-counter

yarn add react-strp-counter

🚀 Usage

// import STRPCounter
import {STRPCounter} from 'react-strp-counter';
// import CSS
import 'react-strp-counter/css';

<STRPCounter
    value={1234567.89} // REQUIRED
    fontSize="48px" // optional
    minLength={9} // optional
    delimiter="," // optional
    decimalSeparator="." // optional
    unitLabel="USD" // optional
    unitLabelPosition="left" // optional
    rollingMode={true} // optional
    stepDuration={0.05} // optional
    easing={"cubic-bezier(0.33,0.81,0.1,1.02)"} // optional
/>

🧩 Props

Prop	Type	Required	Default	Description
`value`	`number \| string`	✅	—	The numeric value or formatted string to render
`fontSize`	`string`	❌	`"28px"`	Font size (used as `--strp_fontsize` CSS variable)
`minLength`	`number`	❌	—	Pad with zeroes on the left to reach minimum character length, used to avoid layout shifts when your number has to add a digit from the left side, optional, but I highly suggest to always use this
`rollingMode`	`boolean`	❌	`false`	If true, enables jackpot-style rolling animation
`stepDuration`	`number`	❌	0.05	Optional, used with rollingMode, Per-digit step duration (in seconds) used for timing delays
`delimiter`	`string \| false`	❌	`false`	Thousands delimiter (e.g. ",", " ")
`decimalSeparator`	`string \| false`	❌	`false`	Decimal point (e.g. "."), always add 2 decimals if you use this
`unitLabel`	`string \| React.ReactNode`	❌	—	Optional unit (e.g. "$", "kg", "`<div />`", "`<svg />`" etc.)
`unitLabelPosition`	`'left' \| 'right'`	❌	`"left"`	Where to place the unit label
`easing`	`string \| false`	❌	`"cubic-bezier(0.33, 0.81, 0.1, 1.02)"`	If set to "false" component will use "linear" instead. Feel free to pass your custom easing

🧠 Best Practices

Use tabular fonts (e.g. Roboto Mono, JetBrains Mono, Menlo, SF Mono) for perfect alignment.

Font used in demo is Big Shoulders Stencil

🎨 Styling (Bring Your Own FONT)

You are required to supply your own FONT.

The package does not include any fonts to make it as lightweight as possible.

Code below:

.strp_counter_wrap {
    --strp_fontfamily: 'YOUR CUSTOM FONT FAMILY';
}

:root {
    --strp_fontfamily: 'YOUR CUSTOM FONT FAMILY';
}

🎨 Styling (for RTL users)

Everything inside the component is forced to render in LTR state, if you supply a RTL unitLabel please force it to be rendered as RTL

.strp_counter_wrap .YOUR_CUSTOM_UNITLABEL {
    direction: rtl !important;
}

Animation Modes

1. Default Mode (rollingMode: false)

Digits animate directly to the new value using CSS transitions.
No infinite-roll illusion; transitions go straight to the next index.
Transitions are smooth but not "slot machine style".
Ideal for standard animated counters and real-time updates.

2. Rolling Mode (rollingMode: true)

Digits roll upward through a sequence of 10 values to reach the next digit.
Designed to mimic a jackpot / slot machine animation.
Digits on the right change first; left digits delay proportionally.
After rolling, digits snap back to correct value without transition (visually seamless).
Ideal for flashy counters, jackpots, or game-like UIs.

Ripple Effect Explained

Digits that change closer to the right animate first. Those to the left wait slightly longer.

This creates a smooth ripple reminiscent of jackpot reels or odometers.

If a digit doesn’t change, it doesn't animate.

Performance

This package is designed to animate without triggering any React re-renders or layout thrashing. No animations are handled via JavaScript after setup. All transitions are GPU-accelerated and run purely via CSS variables.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

MIT

stripearmy / react-strp-counter