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
import
s jquery
.
Using directly in a script tag
- Get the release that you want from releases/tags (or
bower install isInViewport
ornpm install --save is-in-viewport
) - Copy/link either
isInViewport.js
orisInViewport.min.js
and the respective sourcemap from thelib
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 div
s that are in the viewport.
Advanced usage
in-viewport
pseudo-selector
Using $( '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 to0
viewport
defaults towindow
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
is0
orundefined
it is actually equal totolerance: $(viewport).height()
and not0
.
This makes it easier for developers to have the whole viewport
available to them as a valid viewport
.
isInViewport
function
Using exposed $( '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 to0
viewport
defaults towindow
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 sincejQuery.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
asis-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 toisInViewport
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 ofrun
- When available,
isInViewport
now usesSizzle.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
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
sincedo
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 theviewport
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.