Home

Awesome

isInViewport.js

Build Status CDNJS

An ultra-light jQuery plugin that tells you if the element is in the viewport, but with a twist.

Did you say demo (inclusive of tests)?

For a more performant alternative, please take a look at observe-element-in-viewport which uses the new IntersectionObserver API. Please keep in mind that you might have to ship a polyfill for IntersectionObserver depending on the browsers you support.

Note: If you need this in a React application, please use the use-is-in-viewport hook.

Installation

Using in a module

npm install --save is-in-viewport

You can then require('is-in-viewport') or import 'is-in-viewport' in your code. It will automagically work with the bundler of your choice. If it breaks, please feel free to open an issue.

Example usage in an ES6/ES2015 module is shown in the examples/es6-example folder.

Note: isInViewport is a side-effecting module. It imports jquery that you have installed and attaches itself on it. As a consequence, isInViewport requires jquery to be installed as a peer dependency. Your bundling will fail if jquery isn't installed as is-in-viewport imports jquery.

Using directly in a script tag

Usage

<a name="bu"/>

Basic usage

$( 'selector:in-viewport' )

When used as a selector it returns all the elements that match. Since it returns the element(s) it can thus be chained with other jQuery methods. It can also be used with jquery's .is.

Example:
$( 'div:in-viewport' ).css( 'background-color', 'red' );
// same as
var $div = $( 'div' );
if ( $div.is( ':in-viewport' ) ) {
  $div.css( 'background-color', 'red' );
}

Both of the above will set the background-color as red for all divs that are in the viewport.

Advanced usage

Using in-viewport pseudo-selector
$( 'selector:in-viewport( tolerance[, viewport selector] )' )

This returns all the elements that are in the viewport while taking into account the tolerance criterion.

Since it returns the element(s) it can thus be chained with other jQuery methods.

When a viewport selector is specified, it uses that to calculate if the element is in that viewport or not.

When a viewport selector is not specified, it defaults to window as the viewport.

The viewport selector is any valid jQuery selector.

Defaults:
Example:
//example 1
//the height of tolerance region is 100px from top of viewport
$( 'div:in-viewport( 100 )' ).css( 'background-color', 'red' );

//example 2
//the height of tolerance region is (viewport.height - 100px) from top of viewport
$( 'div:in-viewport( -100 )' ).css( 'background-color', 'green' );

//example 3
$('#viewport > div.box:in-viewport( 100, #viewport )').css( 'background-color', 'blue' )
                                                      .text( 'in viewport' );

Example 1 will set the background-color as red for all divs that are in the viewport with a tolerance of 100px.

Example 2 will set the background-color as green for all divs that are in the viewport with a tolerance of viewport height - 100px. This lets the user conveniently provide a tolerance value closer to the viewport height without having to call $(viewport).height() all the time.

Example 3 will set the background-color as blue and text as in viewport for all divs that are in the custom viewport given by #viewport and with a tolerance of 100px.

With the advanced usage it becomes very easy to build things like menus with items that get auto-highlighted based on which section you are on, transition effects when an element comes into the viewport, etc.

See the examples in the examples directory for more clarity.

Note:

This makes it easier for developers to have the whole viewport available to them as a valid viewport.

Using exposed isInViewport function
$( 'selector' ).isInViewport({ tolerance: tolerance, viewport: viewport })

This returns all the elements that are in the viewport while taking into account the tolerance criterion.

Since it returns the element(s) it can thus be chained with other jQuery methods.

When a viewport is specified, it uses that to calculate if the element is in that viewport or not.

When a viewport is not specified, it defaults to window as the viewport.

The viewport is a valid DOM element or jQuery wrapped DOM element, NOT a selector string.

Defaults:
Example:
//example 1
//the height of tolerance region is 100px from top of viewport
$( 'div' ).isInViewport({ tolerance: 100 }).css( 'background-color', 'red' );

//example 2
//the height of tolerance region is (viewport.height - 100px) from top of viewport
$( 'div' ).isInViewport({ tolerance: -100 }).css( 'background-color', 'green' );

//example 3
var $viewport = $('#viewport');

$viewport
  .find('div.box')
  .isInViewport({ tolerance: 100, viewport: $viewport })
  .css( 'background-color', 'blue' )
  .text( 'in viewport' );

Support

Chrome, Firefox 3.5+, IE9+, Safari 5+, Opera 10.5+

Note

Changelog

3.0.3

3.0.2

3.0.1

3.0.0

2.4.2

2.4.1

2.4.0

2.3.1

2.3.0

2.2.5

2.2.4

2.2.3

2.2.2

2.2.1

2.2.0

2.1.0

//usage 1: pass a function
$( 'div:in-viewport' )
  .do(function(){
    console.log( this ); //will log the current jQuery element object it's being called on
  })
  .css( 'background-color', 'red' );

//usage 2: pass an array of functions
var fnArray = [
                function(){ console.log("Fn 1: %o", this); },
                function(){ console.log("Fn 2: %o", this); }
                //or say another function that maybe adds
                //elements to be tracked when in viewport
              ];
$( 'div:in-viewport' ).do(fnArray);

2.0.0

//removed
$( selector ).isInViewport( {"tolerance" :100, "debug": true} )

//current usage
$( 'selector:in-viewport( 100 )' )

1.1.1

1.1.0