react-rolling-number

A smooth, customizable rolling number animation component for React.

English | Korean

Table of Contents

1. Why react-rolling-number?
2. 📦 Installation
3. ⚡️ Quick Start
4. ⚙️ Props
5. 👩🏻‍⚖️ License

Why react-rolling-number?

Existing number animation libraries are often difficult to customize, have limited number format coverage, or require additional code to handle runtime style changes because they accept styles as inline props.

react-rolling-number addresses these inconveniences and helps you implement elegant animations right away.

Features

• Smooth, elegant, continuous rolling animations powered by Motion.
• Built-in TypeScript support.
• Inherits parent font style and responds to runtime style changes.
• Support positive/negative signs.
• Support various number formats (decimals, scientific notation, toFixed, etc.).
• Automatic & Animated thousands separators. Can be toggled off if needed.

For Animation

• Adjustable rolling and width expansion duration.
• Custom easing with cubic-bezier support.
• Animate only changed digits or all digits at once.
• Customizable rolling direction, width expansion direction when digits change.
• Stagger animation for sequential digit/comma/dot transitions.

Try it out on the demo site.

📦 Installation

# npm
npm install react-rolling-number

# yarn
yarn add react-rolling-number

# pnpm
pnpm add react-rolling-number

Important

This library requires React as a peer dependency.

⚡️ Quick Start

React

import { Roller } from 'react-rolling-number';

function Component() {
  return <Roller value={123456} />;
}

Next.js (13+)

'use client';

import { Roller } from 'react-rolling-number';

function Component() {
  return <Roller value={123456} />;
}

⚙️ Props

Name	Type	Default	Description
value	number | string	required	The number to display
commaize	boolean	true	Add thousands separators
showPlusSign	boolean	false	Show + sign for positive numbers
align	'left' | 'center' | 'right'	'center'	Anchor point for width expansion
prefix	ReactNode	-	Content to display before the number
suffix	ReactNode	-	Content to display after the number
animation	RollerAnimationType	-	Animation configuration

Animation Options (RollerAnimationType)

Name	Type	Default	Description
rollWay	'up' | 'down'	'down'	Direction of rolling animation
rollDuration	number	0.6	Duration of roll animation (seconds)
shiftDuration	number	0.45	Duration of width shift animation (seconds)
stagger	boolean	false	Animate digits/separators/decimals sequentially
animateDiff	boolean	false	Only animate digits that changed
ease	Easing	expoOut	Cubic-bezier based easing function

👩🏻‍⚖️ License

MIT © Sanghyeok Park (fecapark). For more details, see LICENSE