React CountUp

A configurable React component wrapper around CountUp.js.

Click here to view on CodeSandbox.

Previous docs

• v3.x
• v4.x
• v5.x

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
      • plugin: CountUpPlugin
      • startOnMount: boolean
      • suffix: string
      • useEasing: boolean
      • useGrouping: boolean
      • useIndianSeparators: boolean
      • easingFn: (t: number, b: number, c: number, d: number) => number
      • formattingFn: (value: number) => string
      • enableScrollSpy: boolean
      • scrollSpyDelay: number
      • scrollSpyOnce: boolean
      • 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
    • Trigger of transition
    • Run if in focus
    • Set accessibility properties for occupation period
  • License

Installation

yarn add react-countup

Usage

importCountUpfrom'react-countup';

Simple example

<CountUpend={100}/>

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

Render prop example

<CountUpstart={-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><spanref={countUpRef}/><buttononClick={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

<CountUpstart={0}end={100}>{({ countUpRef, start })=>(<div><spanref={countUpRef}/><buttononClick={start}>Start</button></div>)}</CountUp>

Autostart with render prop

Render start value but start transition on first render:

<CountUpstart={0}end={100}delay={0}>{({ countUpRef })=>(<div><spanref={countUpRef}/></div>)}</CountUp>

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

Delay start

<CountUpdelay={2}end={100}/>

Hook

Simple example

import{useCountUp}from'react-countup';constSimpleHook=()=>{useCountUp({ref: 'counter',end: 1234567});return<spanid="counter"/>;};

Complete example

import{useCountUp}from'react-countup';constCompleteHook=()=>{constcountUpRef=React.useRef(null);const{ start, pauseResume, reset, update }=useCountUp({ref: countUpRef,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><divref={countUpRef}/><buttononClick={start}>Start</button><buttononClick={reset}>Reset</button><buttononClick={pauseResume}>Pause/Resume</button><buttononClick={()=>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

plugin: CountUpPlugin

Define plugin for alternate animations

startOnMount: boolean

Use for start counter on mount for hook usage.

Default: true

suffix: string

Static text after the transitioning value.

useEasing: boolean

Enables easing. Set to false for a linear transition.

Default: true

useGrouping: boolean

Enables grouping with separator.

Default: true

useIndianSeparators: boolean

Enables grouping using indian separation, f.e. 1,00,000 vs 100,000

Default: false

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.

To prevent component from unnecessary updates this function should be memoized with useCallback

enableScrollSpy: boolean

Enables start animation when target is in view.

scrollSpyDelay: number

Delay (ms) after target comes into view

scrollSpyOnce: boolean

Run scroll spy only once

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

Trigger of transition

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.

Run if in focus

You need to check if your counter in viewport, react-visibility-sensor can be used for this purpose.

importReactfrom'react';importCountUpfrom'react-countup';importVisibilitySensorfrom'react-visibility-sensor';import'./styles.css';exportdefaultfunctionApp(){return(<divclassName="App"><divclassName="content"/><VisibilitySensorpartialVisibilityoffset={{bottom: 200}}>{({ isVisible })=>(<divstyle={{height: 100}}>{isVisible ? <CountUpend={1000}/> : null}</div>)}</VisibilitySensor></div>);}

Note: For latest react-countup releases there are new options enableScrollSpy and scrollSpyDelay which enable scroll spy, so that as user scrolls to the target element, it begins counting animation automatically once it has scrolled into view.

import'./styles.css';importCountUp,{useCountUp}from'react-countup';exportdefaultfunctionApp(){useCountUp({ref: 'counter',end: 1234567,enableScrollSpy: true,scrollSpyDelay: 1000,});return(<divclassName="App"><divclassName="content"/><CountUpend={100}enableScrollSpy/><br/><spanid="counter"/></div>);}

Set accessibility properties for occupation period

You can use callback properties to control accessibility:

importReactfrom'react';importCountUp,{useCountUp}from'react-countup';exportdefaultfunctionApp(){useCountUp({ref: 'counter',end: 10,duration: 2});const[loading,setLoading]=React.useState(false);constonStart=()=>{setLoading(true);};constonEnd=()=>{setLoading(false);};constcontainerProps={'aria-busy': loading,};return(<><CountUpend={123457}duration="3"onStart={onStart}onEnd={onEnd}containerProps={containerProps}/><divid="counter"aria-busy={loading}/></>);}

Plugin usage

import{CountUp}from'countup.js';import{Odometer}from'odometer_countup';exportdefaultfunctionApp(){useCountUp({ref: 'counter',end: 1234567,enableScrollSpy: true,scrollSpyDelay: 1000,plugin: Odometer,});return(<divclassName="App"><spanid="counter"/></div>);}

License

MIT