JavaScripting

The definitive source of the best
JavaScript libraries, frameworks, and plugins.


  • ×

    Count Up.js

    Animates a numerical value by counting to it
    Filed under 

    • 🔾76%Overall
    • 5,455
    • 11.3 days
    • 🕩1045
    • 👥19

    CountUp.js

    CountUp.js is a dependency-free, lightweight Javascript class that can be used to quickly create animations that display numerical data in a more interesting way.

    Despite its name, CountUp can count in either direction, depending on the start and end values that you pass.

    CountUp.js supports all browsers. MIT license.

    Try the demo


    New in 2.0

    • Completely rewritten in Typescript! The distributed code is still Javascript.
    • New cleaner method signature.
    • Tests with Jest. As much code coverage as possible mocking requestAnimationFrame.
    • Smart easing: CountUp intelligently defers easing until it gets close enough to the end value for easing to be visually noticeable. Configureable in the options.
    • Separate bundles for with and without the requestAnimationFrame polyfill. Choose countUp.min.js for modern browsers or countUp.withPolyfill.min.js for IE9 and older, and Opera mini.

    CountUp is now distributed as a ES6 module - see below for how to include it in your project.

    See Also


    Usage:

    On npm: countup.js

    Params:

    • target: string | HTMLElement | HTMLInputElement - id of html element, input, svg text element, or DOM element reference where counting occurs
    • endVal: number - the value you want to arrive at
    • options?: CountUpOptions - optional configuration object for fine-grain control

    Options (defaults in parentheses):

    interface CountUpOptions {
      startVal?: number; // number to start at (0)
      decimalPlaces?: number; // number of decimal places (0)
      duration?: number; // animation duration in seconds (2)
      useGrouping?: boolean; // example: 1,000 vs 1000 (true)
      useEasing?: boolean; // ease animation (true)
      smartEasingThreshold?: number; // smooth easing for large numbers above this if useEasing (999)
      smartEasingAmount?: number; // amount to be eased for numbers above threshold (333)
      separator?: string; // grouping separator (',')
      decimal?: string; // decimal ('.')
      // easingFn: easing function for animation (easeOutExpo)
      easingFn?: (t: number, b: number, c: number, d: number) => number;
      formattingFn?: (n: number) => string; // this function formats result
      prefix?: string; // text prepended to result
      suffix?: string; // text appended to result
      numerals?: string[]; // numeral glyph substitution
    }
    

    Example usage:

    const countUp = new CountUp('targetId', 5234);
    if (!countUp.error) {
      countUp.start();
    } else {
      console.error(countUp.error);
    }
    

    Pass options:

    const countUp = new CountUp('targetId', 5234, options);
    

    with optional callback:

    countUp.start(someMethodToCallOnComplete);
    
    // or an anonymous function
    countUp.start(() => console.log('Complete!'));
    

    Other methods:

    Toggle pause/resume:

    countUp.pauseResume();
    

    Reset the animation:

    countUp.reset();
    

    Update the end value and animate:

    countUp.update(989);
    

    Including CountUp

    CountUp v2 is distributed as an ES6 module because it is the most standardized and most widely compatible module for browsers. For compatibility with IE and older versions of Firefox (< 60), if you are not using a build tool, you will need a module loader polyfill. You can read more about ES6 modules, using the module polyfill and more here. If you are interested in a different module wrapping, you could install a previous release because I've experimented with many of them. The CountUp code is the same; the module wrappings were changed.

    • UMD - npm i countup.js@2.0.0.
    • AMD - npm i countup.js@2.0.1.
    • commonjs - npm i countup@2.0.3.

    For the examples below, first install CountUp. This will give you the latest:

    npm i countup.js
    

    Example with vanilla js

    This is what I used in the demo. Checkout index.html and demo.js.

    main.js:

    import { CountUp } from './js/CountUp.min.js';
    
    window.onload = function() {
      var countUp = new CountUp('target', 2000);
      countUp.start();
    }
    

    Include in your html. Notice the type attribute:

    <script src="./js/countUp.min.js" type="module"></script>
    <script src="./main.js" type="module"></script>
    

    🎉 Done! Keep in mind to run locally you'll need a simple local server setup like this (test the demo locally by running npm run serve) because otherwise you may see a CORS error when your browser tries to load the script as a module.

    Example with Webpack

    main.js:

    import { CountUp } from 'countup.js';
    
    window.onload = function () {
      var countUp = new CountUp('countup', 2000);
      countUp.start();
    }
    

    🎉 Done!

    If you have included CountUp in another type of project and want to help the community, please add it to the README and make a PR.


    Contributing

    Before you make a pull request, please be sure to follow these instructions:

    1. Do your work on src/countUp.ts
    2. Run tests: npm t
    3. Run npm run build, which copies and minifies the .js files to the dist folder.
    4. Serve the demo by running npm run serve and visit http://localhost:8080 to make sure it counts.
    Show All