Skip to content

Bolin-Sun/countUp.js

 
 

Repository files navigation

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.

Jump to:

CountUp for frameworks and plugins:

Features

  • Highly customizeable with a large range of options, you can even substitute numerals.
  • 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 modern and legacy browsers, 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.

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, though a UMD module is also included. 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.

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="./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.

For Webpack and other build systems

Import from the package, instead of the file location:

import { CountUp } from 'countup.js';

UMD module

CountUp is also wrapped as a UMD module in ./dist/countUp.umd.js and it exposes CountUp as a global variable on the window scope. To use it, include countUp.umd.js in a script tag, and invoke it like so:

var numAnim = new countUp.CountUp('myTarget', 2000);
numAnim.start()

Contributing

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

  1. Do your work on src/countUp.ts
  2. Lint: npm run lint
  3. Run tests: npm t
  4. Build: npm run build
  5. Serve the demo by running npm start and check the demo to make sure it counts.

About

Animates a numerical value by counting to it

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • TypeScript 48.9%
  • JavaScript 30.1%
  • HTML 21.0%