isInViewport.js

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

• Get the release that you want from releases/tags (or bower install isInViewport or npm install --save is-in-viewport)
• Copy/link either isInViewport.js or isInViewport.min.js and the respective sourcemap from the lib folder to your folder containing your scripts
• Add it after you include jQuery
• You're ready to go!

Usage

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:

• tolerance defaults to 0
• viewport defaults to window

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:

• When tolerance is 0 or undefined it is actually equal to tolerance: $(viewport).height() and not 0.

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:

• tolerance defaults to 0
• viewport defaults to window

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

• :in-viewport selector does support chaining.

Changelog

3.0.3

• Use jQuery.expr.pseudos when found since jQuery.expr[':'] is deprecated

3.0.2

• Support new rollup properties and get rid of removed rollups properties (moduleId, moduleName, etc)

3.0.1

• Fix jQuery no conflict mode issue (#39)

3.0.0

• Remove the deprecated $(el).do method
• Remove support for browsers < { IE9, Safari 5, Opera 10.5, Firefox 3.5 }
• Add support for modules and bundlers. You can now import 'is-in-viewport'/require('is-in-viewport') in your project (yay!)
• Add properly functioning sourcemaps for easier debugging

2.4.2

• Remove postInstall script which was breaking builds

2.4.1

• Undo 2.4.0 as is-in-viewport already exists on bower and isn't owned by me

2.4.0

• Update bower.json to comply with new validations
• Rename package on bower to match with that on npm i.e., is-in-viewport

2.3.1

• Remove unnecessary boolean coercion

2.3.0

• Re-exposed isInViewport with saner semantics. You can now pass options as JS objects to isInViewport and hence can now do things like:

  var $viewport = $(<viewport selector>);
  
  $viewport
    .find(<selector for elements>)
    .isInViewport({ tolerance: 100, viewport: $viewport }) // <- passing the viewport jQuery object in directly
    .css(color: 'red');

• Deprecated do in favour of run
• When available, isInViewport now uses Sizzle.selectors.createPseudo

2.2.5

• Updated readme to point to new demo. Mostly a bump for npm to pickup the new readme.

2.2.4

• Pulled #15(fixes horizontal viewport check)

2.2.3

• Allow use as CommonJS -> #19
• Fixed gruntfile. It now generates proper filenames during build.

2.2.2

• Published to npm
• Updated install instructions to include npm

2.2.1

• Pulled in a few bugfixes
• Fixed ie8 bugs

2.2.0

• Aliased the .do method with .run since do is a reserved word and errors out when used as a property in IE. To be on the safer side, use .run to chain any arbitrary function or an array of functions.

2.1.0

• Added a .do method that lets the user chain any arbitrary function or an array of functions. Example:

//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

• Added support for negative tolerance values that are now relative to the viewport height
• Added support for custom viewport selector (see Advanced usage)
• Added support for checking if an element is in viewport both horizontally and vertically. (checks both now)
• Removed support for the old usage syntax in favour of the :in-viewport selector i.e.,

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

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

• Removed the debug option because, lets be honest, no one really used it.
• Removed the weird code that handled end of page condition in the core. It's the user's prerogative to do what he/she wants when their page is scrolled to end of page.

1.1.1

• Added bower support.

1.1.0

• Added support for :in-viewport selector as per joeframbach's suggestion.