Getting Started

Welcome to the react-animate-numbers library! This guide will walk you through the setup process and help you integrate this awesome animated numbers component into your React projects. Follow these steps to get up and running quickly!

Installation

To start using react-animate-numbers, you need to install it via npm or yarn. Open your terminal in the root of your React project and run the following command:

Using npm:

cmd

npm install react-animate-numbers

Using yarn:

cmd

yarn add react-animate-numbers

Using pnpm:

cmd

pnpm add react-animate-numbers

Once installed, you're ready to use the component in your project.

Basic Usage

Here’s a quick example to show how easy it is to use react-animate-numbers:

tsx

import React, { useState, useEffect } from "react";
import AnimatedNumbers from "react-animate-numbers";
 
function App() {
  const [number, setNumber] = useState(123);
 
  useEffect(() => {
    const interval = setInterval(() => {
      setNumber((prev) => prev + 1);
    }, 2000);
 
    return () => clearInterval(interval);
  }, []);
 
  return (
    <div>
      <AnimatedNumbers value={number} maxLength={5} />
    </div>
  );
}
 
export default App;

Result:

What’s Happening?

The value prop is the number that will be animated.
The maxLength prop ensures that the number always has a fixed length by padding with zeros if needed (e.g., 000123 for a maxLength of 6).
The animation automatically plays whenever the value changes.

Understanding Props

The AnimatedNumbers component accepts several props that control its functionality and appearance:

Prop	Type	Required	Default	Description
`value`	`number`	Yes	—	The number to animate and display.
`maxLength`	`NumberRange<1, 21>`	Yes	—	Maximum length of digits to display. Pads with zeros if necessary.
`options`	`object`	No	`{}`	Additional settings to customize animation speed, style, etc.

Customization Options

The options prop provides several ways to customize the animation and styling of the numbers. Here’s a breakdown of the available options:

Option	Type	Default	Description
`animationSpeed`	`"sm"`, `"md"`, `"lg"`	`"md"`	Speed of the animation: small (fast), medium, or large (slow).
`animationType`	`"ease"`, `"linear"`, `"ease-in"`, `"ease-out"`, `"ease-in-out"`	`"ease-in-out"`	Type of animation easing for a smoother effect.
`backgroundColor`	`string`	`""`	Background color behind each digit (optional).
`bold`	`boolean`	`true`	Whether the digits should be bold (default is `true`).
`border`	`string`	`""`	Adds a border around each digit container (e.g., `"1px solid red"`).
`color`	`string`	`""`	The color of the digits.
`fontSize`	`number`	`44`	Font size of the digits (in pixels).
`gap`	`number`	`0`	Space between each digit (useful for spacing adjustments).

Example with Custom Options:

<AnimatedNumbers
  value={54321}
  maxLength={6}
  options={{
    color: "#4A90E2",
    fontSize: 60,
    border: "2px solid #D1D5DB",
    backgroundColor: "#F9FAFB",
    bold: true,
    animationSpeed: "sm",
    gap: 5,
  }}
/>

Result:

Examples