@morr/withinviewport

    2.1.2 • Public • Published

    Within Viewport

    Determine whether elements are within the viewport

    Includes:

    • A standalone, plain JavaScript function, withinviewport()
    • AMD and Node/CommonJS support
    • Optional jQuery plugin with handy selectors and shorthand methods

    All of the above offer the same features.

    Note

    Although this plugin is still actively maintained, it will eventually be made obsolete by the Intersection Observer API. You can check the current state of browser compatibility at caniuse.com. Meanwhile, withinviewport will continue to work on current and legacy browsers.

    Installation

    AMD, Node.js, CommonJS

    NPM

    npm install withinviewport

    And then:

    var withinviewport = require('withinviewport');

    Bower:

    bower install within-viewport

    Traditional include

    Standalone (no jQuery):

    <script src="withinviewport.js"></script>

    jQuery plugin:

    <script src="withinviewport.js"></script>
    <script src="jquery.js"></script>
    <script src="jquery.withinviewport.js"></script>

    Usage

    Basic

    // Returns true if the element is entirely within view of the window
    var elem = document.getElementById('#myElement');
    withinviewport(elem);

    Advanced

    // Test against only some sides of the window for faster performance
    withinviewport(elem, {sides: 'left'});
    // Pick another element to act as the viewport (instead of `window`)
    withinviewport(elem, {container: document.getElementById('myElem')});
    // Define your own viewport crop by specifying thresholds for each side
    // Example: element is at least 12px inside the top and right of the viewport
    withinviewport(elem, {top: 12, right: 12});

    For more options, see Settings section below.

    Shorthand notation

    // These will use the default thresholds; see 'Settings' section below
    withinviewport(elem, 'bottom right');
    withinviewport.left(elem);

    jQuery plugin

    Usage

    Basic

    // Returns true if the element is entirely within the viewport
    $('#myElement').is(':within-viewport');
    // Returns a jQuery object of all <div>s that are within the viewport
    $('div').withinviewport();

    Advanced

    There are shorthand selectors and methods for testing against only one edge of the viewport.

    // Returns true if the element is within the left edge of the viewport
    // Also works with 'top', 'right', and 'bottom'
    $('#myElement').is(':within-viewport-left');
    // Returns a jQuery collection of all <div>s within the left edge of the viewport
    $('div').withinviewportleft();
    // Same as above, but only elements that are at least 12px inside the left edge
    $('div').withinviewportleft({left: 12});

    These shortcuts will result in slightly better performance if you're testing hundreds or thousands of elements.

    Live updating

    If you're looking to keep tabs on elements' whereabouts at all times, you can bind to the window's resize and scroll events. Instead of scroll, I recommend using James Padolsey's scrollStop event since firing on every window.scroll event will bring your UI to its knees.

    $(window).on('resize scrollStop', function() {
        // Your code here...
    
        // Example:
        $('div')
            // Momentarily declare all divs out of the viewport...
            .removeClass('within-viewport');
            // Then filter them to reveal which ones are still within it
            .filter(':within-viewport')
                .addClass('within-viewport');
    });

    A future version will allow you to fire custom events when elements pass in and out of the viewport.

    Settings

    This applies to both the jQuery plugin and standalone function.

    Use the object withinviewport.defaults to define your page's practical viewport compared to the actual browser window.

    Custom viewport element

    If you want to test whether an element is within a scrollable parent element (e.g. which has overflow: auto), assign the parent element to the container property:

    $('.child-element').withinviewport({
        container: $('.parent-element')
    });

    Custom boundaries

    For example, a fixed header with a height of 100px that spans the entire width of the page effectively lowers the viewport by 100px from the top edge of the browser window:

    withinviewport.defaults.top = 100;

    If you only care about some edges of the viewport, you can specify them to improve performance:

    withinviewport.defaults.sides = 'left bottom';

    You can also pass settings on the fly to temporarily override the defaults:

    withinviewport(elem, {sides:'left bottom', left: 40});
    $('div').withinviewport({sides:'left bottom', left: 40});

    Individual elements may have their own settings embedded in a data attribute using object notation. These will override both the defaults any any settings passed to the function on the fly (like the example above).

    <div data-withinviewport-settings="{sides: 'left', top: 40}">

    You can specify negative threshold values to allow elements to reside outside the viewport.

    Browser Support

    • IE 7(?) and higher
    • All the others except Opera Mini
      • Tested in the latest stable Chrome, Firefox, Safari, and IE
      • No "new" JavaScript or quirky techniques are employed so it should work in all other modern browsers not specifically mentioned above

    What's Next

    Please note that the camel case withinViewport method name is deprecated and is no longer supported as of version 2.0.0.

    • Option to fire events when elements pass in and out of the viewport
    • Test against Firefox 3.6, Safari 5.0.1

    Credit

    Within Viewport is inspired by these similar utilities which only reflect whether an element is at least partially in view:

    License

    Have fun with it — ISC. See included LICENSE file.

    Author

    Craig Patik, patik.com & @craigpatik

    Install

    npm i @morr/withinviewport

    DownloadsWeekly Downloads

    4

    Version

    2.1.2

    License

    ISC

    Unpacked Size

    17.1 kB

    Total Files

    4

    Last publish

    Collaborators

    • avatar