react-use-count-up

A React hook with Typescript typings for animating a number counting up

Installation

npm i react-use-count-up

Usage

1import { useCountUp } from 'react-use-count-up';
2
3const MyComponent = () => {
4  const value = useCountUp({ start: 0, end: 42, duration: 500 });
5
6  return (
7    <>{value}</>
8  );
9}

Options

useCountUp takes a configuration object with the following keys:

start

the number to start with

end

the number to end at

duration

the duration of the animation in miliseconds

started (optional)

whether the animation has started or not

default true

1import { useState } from 'react';
2import { useCountUp } from 'react-use-count-up';
3
4
5const MyComponent = () => {
6  const [ started, setStarted ] = useState(false);
7  const value = useCountUp({ start: 0, end: 42, duration: 500, started });
8
9  return (
10    <>
11      <div>Value: {value}</div>
12      <button onClick={() => setStarted(true)}>Start</button>
13    </>
14  );
15}

formatter (optional)

a function in the form (value: number) => string to be applied to the return value

default v => v.toFixed(0)

📝 If supplying a formatter function, ensure that you provide a constant reference to the useCountUp hook. To prevent unintended re-renders, either create the function outside your component, or memoize it

1import { useCountUp } from 'react-use-count-up';
2
3// declared outside the component
4const formatter = new Intl.NumberFormat('en-CA', { style: 'currency', currency: 'CAD' }).format
5
6const MyComponent = () => {
7  const value = useCountUp({ start: 0, end: 42, duration: 500, formatter });
8
9  return (
10    <>{value}</>
11  );
12}

easingFunction (optional)

a custom easing function in the form (t: number, b: number, c: number, d: number) => number or a string that equals one of the built-in easing functions used to be used to calculate the return value

default 'easeOutExpo'

📝 If supplying an easing function, ensure that you provide a constant reference to the useCountUp hook. To prevent unintended re-renders, either create the function outside your component, or memoize it.

1import { useCountUp } from 'react-use-count-up';
2
3// declared outside the component
4const easeOutCirc = (t, b, c, d) => {
5  t /= d;
6  t--;
7  return c * Math.sqrt(1 - t * t) + b;
8};
9
10const MyComponent = () => {
11  const value = useCountUp({ start: 0, end: 42, duration: 500, easingFunction: easeOutCirc });
12
13  return (
14    <>{value}</>
15  );
16}

Easing

Built-in Easing Functions

• linear
• easeOutExpo
• easeInExpo
• easeOutQuad
• easeInQuad
• easeOutCubic
• easeInCubic
• easeOutQuart
• easeInQuart
• easeOutQuint
• easeInQuint

To use one of these built-in easing functions, supply a string to the configuration object

1const options = {
2  start: 3,
3  end: 99,
4  duration: 2000,
5  easingFunction: 'easeOutCubic',
6  ...
7}

Custom Easing Functions

Custom easing functions are in the form (t: number, b: number, c: number, d: number) => number and take the following paramters:

t

the amount of time elapsed

b

the start value

c

the total change (i.e. end - start)

d

the total duration

They return the how far through the animation we are, from 0 to 1.

E.g.,

1const easeOutExpo = (t, b, c, d) => {
2  return (c * (-Math.pow(2, -10 * t / d) + 1)) + b;
3};

Custom Polynomial Higher-Order Function

You can use the custom polynomial higher-order functions easeOutPoly or easeInPoly to create a polynomial easing function of degree n (n = 1 is equivalent to linear, n = 2 is equivalent to quadradic, n = 3 is equivalent to cubic, etc.).

1import { easeOutPoly, useCountUp } from 'react-use-count-up';
2
3const easeOutSeptic = easeOutPoly(7);
4
5const MyComponent = () => {
6  const value = useCountUp({ start: 0, end: 42, duration: 500, easingFunction: easeOutSeptic });
7
8  return (
9    <>{value}</>
10  );
11}