react-countup

What is react-countup?

The react-countup package is a React component that allows you to create animated number counters. It is useful for displaying statistics, financial data, or any other numerical information that benefits from a dynamic presentation.

What are react-countup's main functionalities?

Basic Count Up

This feature allows you to create a simple count-up animation from 0 to a specified number. In this example, the counter will animate from 0 to 100.

<CountUp end={100} />

Custom Start and End Values

You can specify both the start and end values for the count-up animation. Here, the counter will animate from 50 to 150.

<CountUp start={50} end={150} />

Duration

This feature allows you to set the duration of the count-up animation. In this example, the counter will animate from 0 to 100 over a period of 5 seconds.

<CountUp end={100} duration={5} />

Formatting Numbers

You can format the numbers with separators for better readability. In this example, the counter will animate to 1,000 with a comma as the thousands separator.

<CountUp end={1000} separator=',' />

OnComplete Callback

This feature allows you to execute a callback function once the count-up animation is complete. Here, a message 'Completed!' will be logged to the console when the counter reaches 100.

<CountUp end={100} onEnd={() => console.log('Completed!')} />

Other packages similar to react-countup

react-animated-numbers

The react-animated-numbers package provides a similar functionality to react-countup, allowing you to animate numbers in a React application. It offers more customization options for the animation style and easing functions, making it a good alternative for more complex animations.

react-spring

The react-spring package is a spring-physics-based animation library for React applications. While it is not specifically designed for counting numbers, it can be used to create complex animations, including number animations, with more control over the animation physics and behavior.

react-flip-numbers

The react-flip-numbers package provides a unique flip animation for numbers, similar to an old-school flip clock. It offers a different visual style compared to react-countup and can be used to create engaging number animations with a retro feel.

README

React CountUp

A configurable React component wrapper around CountUp.js.

Looking for v3.x docs?

Click here to get to the previous docs.

Table of Contents

• Installation
  • Usage
    • Simple example
    • Render prop example
    • More examples
      • Manually start with render prop
      • Autostart with render prop
      • Delay start
      • Hook
  • API
    • Props
      • className: string
      • decimal: string
      • decimals: number
      • delay: ?number
      • duration: number
      • end: number
      • prefix: string
      • redraw: boolean
      • preserveValue: boolean
      • separator: string
      • start: number
      • suffix: string
      • useEasing: boolean
      • easingFn: (t: number, b: number, c: number, d: number) => number
      • formattingFn: (value: number) => string
      • onEnd: ({ pauseResume, reset, start, update }) => void
      • onStart: ({ pauseResume, reset, update }) => void
      • onPauseResume: ({ reset, start, update }) => void
      • onReset: ({ pauseResume, start, update }) => void
      • onUpdate: ({ pauseResume, reset, start }) => void
    • Render props
      • countUpRef: () => void
      • pauseResume: () => void
      • reset: () => void
      • start: () => void
      • update: (newEnd: number?) => void
  • Protips
  • License

Installation

yarn add react-countup

Usage

import CountUp from 'react-countup';

Simple example

<CountUp end={100} />

This will start a count up transition from 0 to 100 on render.

Render prop example

<CountUp
  start={-875.039}
  end={160527.012}
  duration={2.75}
  separator=" "
  decimals={4}
  decimal=","
  prefix="EUR "
  suffix=" left"
  onEnd={() => console.log('Ended! 👏')}
  onStart={() => console.log('Started! 💨')}
>
  {({ countUpRef, start }) => (
    <div>
      <span ref={countUpRef} />
      <button onClick={start}>Start</button>
    </div>
  )}
</CountUp>

The transition won't start on initial render as it needs to be triggered manually here.

Tip: If you need to start the render prop component immediately, you can set delay={0}.

More examples

Manually start with render prop

<CountUp start={0} end={100}>
  {({ countUpRef, start }) => (
    <div>
      <span ref={countUpRef} />
      <button onClick={start}>Start</button>
    </div>
  )}
</CountUp>

Autostart with render prop

Render start value but start transition on first render:

<CountUp start={0} end={100} delay={0}>
  {({ countUpRef }) => (
    <div>
      <span ref={countUpRef} />
    </div>
  )}
</CountUp>

Note that delay={0} will automatically start the count up.

Delay start

<CountUp delay={2} end={100} />

Hook

Simple example

import { useCountUp } from 'react-countup';

const SimpleHook = () => {
  const { countUp } = useCountUp({ end: 1234567 });
  return <div>{countUp}</div>;
};

Complete example

import { useCountUp } from 'react-countup';

const CompleteHook = () => {
  const { countUp, start, pauseResume, reset, update } = useCountUp({
    start: 0,
    end: 1234567,
    delay: 1000,
    duration: 5,
    onReset: () => console.log('Resetted!'),
    onUpdate: () => console.log('Updated!'),
    onPauseResume: () => console.log('Paused or resumed!'),
    onStart: ({ pauseResume }) => console.log(pauseResume),
    onEnd: ({ pauseResume }) => console.log(pauseResume),
  });
  return (
    <div>
      <div>{countUp}</div>
      <button onClick={start}>Start</button>
      <button onClick={reset}>Reset</button>
      <button onClick={pauseResume}>Pause/Resume</button>
      <button onClick={() => update(2000)}>Update to 2000</button>
    </div>
  );
};

API

Props

className: string

CSS class name of the span element.

Note: This won't be applied when using CountUp with render props.

decimal: string

Specifies decimal character.

Default: .

decimals: number

Amount of decimals to display.

Default: 0

delay: ?number

Delay in seconds before starting the transition.

Default: null

Note: delay={0} will automatically start the count up.

duration: number

Duration in seconds.

Default: 2

end: number

Target value.

prefix: string

Static text before the transitioning value.

redraw: boolean

Forces count up transition on every component update.

Default: false

preserveValue: boolean

Save previously ended number to start every new animation from it.

Default: false

separator: string

Specifies character of thousands separator.

start: number

Initial value.

Default: 0

suffix: string

Static text after the transitioning value.

useEasing: boolean

Enables easing. Set to false for a linear transition.

Default: true

easingFn: (t: number, b: number, c: number, d: number) => number

Easing function. Click here for more details.

Default: easeInExpo

formattingFn: (value: number) => string

Function to customize the formatting of the number

onEnd: ({ pauseResume, reset, start, update }) => void

Callback function on transition end.

onStart: ({ pauseResume, reset, update }) => void

Callback function on transition start.

onPauseResume: ({ reset, start, update }) => void

Callback function on pause or resume.

onReset: ({ pauseResume, start, update }) => void

Callback function on reset.

onUpdate: ({ pauseResume, reset, start }) => void

Callback function on update.

Render props

countUpRef: () => void

Ref to hook the countUp instance to

pauseResume: () => void

Pauses or resumes the transition

reset: () => void

Resets to initial value

start: () => void

Starts or restarts the transition

update: (newEnd: number?) => void

Updates transition to the new end value (if given)

Protips

By default, the animation is triggered if any of the following props has changed:

• duration
• end
• start

If redraw is set to true your component will start the transition on every component update.

License

MIT