Count up

A tiny dependency-free JavaSript library for animating numeric values.

Live Demo: https://bukacekd.github.io/count-up

Features

• easy to use
• rich formatting using Intl.NumberFormat
• possibility to define a custom easing function
• simple configuration and api

Installation

Npm

npm install @js4y/count-up

CDN

<script src="https://unpkg.com/@js4y/count-up/dist/index.js"></script>

Usage

Npm

import {CountUp} from '@js4y/count-up';

new CountUp(document.body, {
    from: 1,
    to: 10
});

CDN

<script src="https://unpkg.com/@js4y/count-up/dist/index.js"></script>

<script>
    new js4y.components.CountUp(document.body, {
    from: 1000,
    to: -1000
});
<script>

Configuration

The component offers a set of configuration items. Below is an overview of them.

new CountUp(element: HTMLElement | string, {
    begin?: Function,
    complete?: Function,
    duration?: number,
    easing?: Function,
    formattter?: Intl.NumberFormat,
    from: number,
    to: number,
    update?: Function
});

begin

required: false, type: Function

The callback function is triggered when the animation starts playing.

new CountUp(document.body, {
    begin: () => {
        console.log('start of animation');
    },
});

complete

required: false, type: Function

The callback function is triggered when the animation is completed.

new CountUp(document.body, {
    complete: () => {
        console.log('end of animation');
    },
});

duration

required: false, type: number

Animation duration in milliseconds.

new CountUp(document.body, {
    duration: 1000
});

easing

required: false, type: Function

A custom easing function of the animation. The function argument represents the animation progress between 0 (start of animation) and 1 (end of animation).

new CountUp(document.body, {
    easing: progress => Math.sin((progress * Math.PI) / 2),
});

Tip: Try one of the easing functions from the https://easings.net/.

formatter

required: false, type: Intl.NumberFormat

The number formatter. Allows wide formatting of numbers by locale. By default the formatting follows the html language of the page.

new Intl.NumberFormat(document.documentElement.lang, {
    maximumFractionDigits: 0,
    minimumFractionDigits: 0
});

To set up your own formatter follow the Intl.NumberFormatter documentation.

from

required: false, type: number

The beginning of the animation range.

new CountUp(document.body, {
    from: 10,
});

For numbers greater than Number.MAX_SAFE_INTEGER (253 - 1) use BigInt.

to

required: false, type: number

The end of animation range.

new CountUp(document.body, {
    to: 100,
});

For numbers greater than Number.MAX_SAFE_INTEGER (253 - 1) use BigInt.

update

required: false, type: Function

Callback function triggered on every frame as soon as the animation starts playing. The function argument represents the animation progress between 0 (start of animation) and 1 (end of animation).

new CountUp(document.body, {
    update: progress => {
        console.log('animation progress', progress.toFixed(2));
    },
});

Methods

create(element, options): CountUp

Creates the component, but without running the animation.

const countUp = CountUp.create(document.body, {
    duration: 1000,
    from: 1,
    to: 10
});

To start the animation, use the constructor.

const countUp = new CountUp(document.body, {
    duration: 1000,
    from: 1,
    to: 10
});

play(): void

The method starts playing the animation.

countUp.play();

pause(): void

The method pauses the animation.

countUp.pause();

cancel(): void

The method cancels the animation.

countUp.cancel();

Browser support

| | | | | | | :-: | :-: | :-: | :-: | :-: | | Chrome 24+ | Edge 12+ | Firefox 29+ | Opera 15+ | Safari 10+ |

License

The project is licensed under MIT license.

Related

• Dialog - A tiny dependency-free JavaSript ES6 library built on a dialog element with minimal configuration.
• Loader - A tiny dependency-free javascript loading spinner component with minimal configuration.
• lockScroll - A set of methods to lock scrolling within an element or an entire page.