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

or

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';
}

or

: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