When in viewport

Handle elements as they enter viewport with this simple and lightweight javascript library. Useful for content lazy loading and applying timed animations. Has no dependencies and weighs less than 2KB.

Is is often useful to transform elements in some way as users scroll your webpage. Sometimes you will do as little as apply a class to html element which just entered viewport. Other times you will load all module resources just as it is displayed to user. Lazy loading can help with your performance budget.

Examples

Next few dummy paragraphs should display and fade in as we scroll down the web page.

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Voluptas amet a accusamus eos numquam sint rerum, ipsum aperiam tempore, dolor, sed ex? Corrupti obcaecati, atque ab ullam cum et nam!

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

WhenInViewport comes with jQuery adapter included - for this small slick animation all we had to write was following code. 


            $('.fadeInParagraph').whenInViewport(function($paragraph) {
                $paragraph.addClass('inViewport');
            });

Same result in plain javascript (without jQuery) is achieved like so: 



            var elements = Array.prototype.slice.call(
                document.getElementsByClassName('fadeInParagraph')
            );

            elements.forEach(function(element) {
                new WhenInViewport(element, function(elementInViewport) {
                    elementInViewport.classList.add('inViewport');
                });
            });

Styling was done as simple css transition that was trigged when new class was applied to element.

Api and options

Different ways and options of running plugin are examined bellow. 



            // As in example above run plugin with callback only
            $('.fadeInParagraph').whenInViewport(function($paragraph) {
                $paragraph.addClass('inViewport');
            });

            // With adjusted options
            $('.fadeInParagraph').whenInViewport(function($paragraph) {
                $paragraph.addClass('inViewport');
            }, {
                threshold: 100 // difference in pixels from user scroll position
            });

            // get instance
            var footerInViewport = $('footer').whenInViewport(function($footer) {
                $footer.addClass('inViewport');
            }).data('whenInViewport');

            // get instance via constructor
            var footerInViewport = new WhenInViewport($('.footer').get(0), function(footer) {
                $(footer).addClass('inViewport');
            });

            // stop whenInViewport listener
            footerInViewport.stopListening();

Plugin options / defaults are exposed in WhenInViewport.defaults namespace so you can easily adjust them globally. List of options is bellow. 


            WhenInViewport.defaults = {
                threshold: 0, // difference in pixels from user scroll position
                context: null // callback context
            };

If you want to set delaying / rate-limiting engine for scroll and resize events (for example delegate to underscores throttle or debounce functions) a method for doing so is exposed: 


            WhenInViewport.setRateLimiter(_.throttle, 250);

If you want to kill all whenInViewport listeners: 


            WhenInViewport.destroy();

When page layout changes and no resize events are fired you might want to tell WhenInViewport to check all of its registered items: 


            WhenInViewport.checkAll();

If you are running jQuery that is is not exposed on global window variable and want to use WhenInViewport via plugin facade: 


            var $ = require('jquery');
            WhenInViewport.registerAsJqueryPlugin($);

Installation

WhenInViewport is packaged as UMD library so you can use it in CommonJS and AMD environment or with browser globals. 


            // install via npm
            npm install when-in-viewport --save

            // if you use bundler
            var WhenInViewport = require('when-in-viewport');

            // or just using browser globals
            var WhenInViewport = window.WhenInViewport;

For browser usage browse dist folder - if working with build tools go with src folder. Download library files from github repo, get them via bower (bower install whenInViewport) or via npm (npm install when-in-viewport)

Fork me on GitHub