Animate when target element is scrolled into view (#273)

* scroll spy!

* allow for multiple scroll-enabled instances

* log error when using scroll spy

* tweaks

Author: inorganik

README.md

@@ -27,6 +27,7 @@ CountUp.js supports all browsers. MIT license.
 
 
 ## Features
+- **Animate when element scrolls into view** - new in v2.1.0. Use option `enableScrollSpy`.
 - **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](#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.
@@ -59,6 +60,8 @@ interface CountUpOptions {
   prefix?: string; // text prepended to result
   suffix?: string; // text appended to result
   numerals?: string[]; // numeral glyph substitution
+  enableScrollSpy?: boolean; // start animation when target is in view
+  scrollSpyDelay?: number; // delay (ms) after target comes into view
 }
 ```
 
@@ -106,11 +109,28 @@ Update the end value and animate:
 ```js
 countUp.update(989);
 ```
+
+### Animate when the element is scrolled into view
+
+Use the scroll spy option to animate when the element is scrolled into view. When using scroll spy, just initialize CountUp but do not call start();
+
+```js
+const countUp = new CountUp('targetId', 989, { enableScrollSpy: true });
+```
+
+**Troubleshooting scroll spy**
+
+CountUp checks the scroll position as soon as it's initialized. So if you initialize it before the DOM renders and your target element is in view before any scrolling, you'll need to re-check the scroll position after the page renders:
+
+```js
+// after DOM has rendered
+countUp.handleScroll();
+```
 ---
 
 ## 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](#umd-module).
+CountUp 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](#umd-module).
 
 For the examples below, first install CountUp. This will give you the latest:
 ```

dist/countUp.d.ts

@@ -13,9 +13,10 @@ export interface CountUpOptions {
     prefix?: string;
     suffix?: string;
     numerals?: string[];
+    enableScrollSpy?: boolean;
+    scrollSpyDelay?: number;
 }
 export declare class CountUp {
-    private target;
     private endVal;
     options?: CountUpOptions;
     version: string;
@@ -36,6 +37,7 @@ export declare class CountUp {
     paused: boolean;
     frameVal: number;
     constructor(target: string | HTMLElement | HTMLInputElement, endVal: number, options?: CountUpOptions);
+    handleScroll(self: CountUp): void;
     private determineDirectionAndSmartEasing;
     start(callback?: (args?: any) => any): void;
     pauseResume(): void;

dist/countUp.js

@@ -13,10 +13,9 @@ var __assign = (this && this.__assign) || function () {
 var CountUp = /** @class */ (function () {
     function CountUp(target, endVal, options) {
         var _this = this;
-        this.target = target;
         this.endVal = endVal;
         this.options = options;
-        this.version = '2.0.8';
+        this.version = '2.1.0';
         this.defaults = {
             startVal: 0,
             decimalPlaces: 0,
@@ -28,7 +27,9 @@ var CountUp = /** @class */ (function () {
             separator: ',',
             decimal: '.',
             prefix: '',
-            suffix: ''
+            suffix: '',
+            enableScrollSpy: false,
+            scrollSpyDelay: 200,
         };
         this.finalEndVal = null; // for smart easing
         this.useEasing = true;
@@ -135,7 +136,37 @@ var CountUp = /** @class */ (function () {
         else {
             this.error = '[CountUp] target is null or undefined';
         }
+        // scroll spy
+        if (window !== undefined && this.options.enableScrollSpy) {
+            if (!this.error) {
+                // set up global array of onscroll functions
+                window['onScrollFns'] = window['onScrollFns'] || [];
+                window['onScrollFns'].push(function () { return _this.handleScroll(_this); });
+                window.onscroll = function () {
+                    window['onScrollFns'].forEach(function (fn) { return fn(); });
+                };
+                this.handleScroll(this);
+            }
+            else {
+                console.error(this.error, target);
+            }
+        }
     }
+    CountUp.prototype.handleScroll = function (self) {
+        if (!self || !window)
+            return;
+        var bottomOfScroll = window.innerHeight + window.scrollY;
+        var bottomOfEl = self.el.offsetTop + self.el.offsetHeight;
+        if (bottomOfEl < bottomOfScroll && bottomOfEl > window.scrollY && self.paused) {
+            // in view
+            self.paused = false;
+            setTimeout(function () { return self.start(); }, self.options.scrollSpyDelay);
+        }
+        else if (window.scrollY > bottomOfEl && !self.paused) {
+            // scrolled past
+            self.reset();
+        }
+    };
     // determines where easing starts and whether to count down or up
     CountUp.prototype.determineDirectionAndSmartEasing = function () {
         var end = (this.finalEndVal) ? this.finalEndVal : this.endVal;

dist/countUp.min.js

@@ -19,10 +19,9 @@
     var CountUp = /** @class */ (function () {
         function CountUp(target, endVal, options) {
             var _this = this;
-            this.target = target;
             this.endVal = endVal;
             this.options = options;
-            this.version = '2.0.8';
+            this.version = '2.1.0';
             this.defaults = {
                 startVal: 0,
                 decimalPlaces: 0,
@@ -34,7 +33,9 @@
                 separator: ',',
                 decimal: '.',
                 prefix: '',
-                suffix: ''
+                suffix: '',
+                enableScrollSpy: false,
+                scrollSpyDelay: 200,
             };
             this.finalEndVal = null; // for smart easing
             this.useEasing = true;
@@ -141,7 +142,37 @@
             else {
                 this.error = '[CountUp] target is null or undefined';
             }
+            // scroll spy
+            if (window !== undefined && this.options.enableScrollSpy) {
+                if (!this.error) {
+                    // set up global array of onscroll functions
+                    window['onScrollFns'] = window['onScrollFns'] || [];
+                    window['onScrollFns'].push(function () { return _this.handleScroll(_this); });
+                    window.onscroll = function () {
+                        window['onScrollFns'].forEach(function (fn) { return fn(); });
+                    };
+                    this.handleScroll(this);
+                }
+                else {
+                    console.error(this.error, target);
+                }
+            }
         }
+        CountUp.prototype.handleScroll = function (self) {
+            if (!self || !window)
+                return;
+            var bottomOfScroll = window.innerHeight + window.scrollY;
+            var bottomOfEl = self.el.offsetTop + self.el.offsetHeight;
+            if (bottomOfEl < bottomOfScroll && bottomOfEl > window.scrollY && self.paused) {
+                // in view
+                self.paused = false;
+                setTimeout(function () { return self.start(); }, self.options.scrollSpyDelay);
+            }
+            else if (window.scrollY > bottomOfEl && !self.paused) {
+                // scrolled past
+                self.reset();
+            }
+        };
         // determines where easing starts and whether to count down or up
         CountUp.prototype.determineDirectionAndSmartEasing = function () {
             var end = (this.finalEndVal) ? this.finalEndVal : this.endVal;