README.md

Element 'in view' Event Plugin

Author: Remy Sharp

Pulled from: http://remysharp.com/2009/01/26/element-in-view-event-plugin/

NOTE: "I" here refers to the original author, Remy Sharp.

I've been preparing a few articles for jQuery for Designers and for .net magazine and in doing so I've had to write a plugin that could prove to be useful to share.

I've created an event that will trigger when the element is scrolled in to the viewport.

Preamble

First of all, this isn't really a plugin. It's a utility of sorts. It's not really a plugin, because you don't call it. It binds on to the scroll event and does the work for you.

Also, I'm aware that there is the lazyload plugin. I've not had real time to play with it, but I suspect there's some similarities, though my inview plugin is extremely stripped down (because I wrote it for a particular purpose). Also note that my code only works for vertical scroll, and not horizontal.

I should also add that this utility/plugin was inspired by Dustin Diaz's detect when an element scrolls in to view code.

##Demo

The example is mostly lorem text, but in the middle of the page is an element whose text reads: "You can't see me". When the element is scrolled in to view it will change to "You found me".

To confirm this, open firebug while the element is out of view, and watch the element in question as you scroll it in to view.

http://jsbin.com/ugupa: (to edit: http://jsbin.com/ugupa/edit)

Download

Download jQuery inview event plugin

Or from github at: http://github.com/zuk/jquery.inview

Usage

The script makes use of the new $.support properties - so it will only work with jQuery 1.3 upwards. If you need to use it with older versions of jQuery, drop a comment, and I'll post an alternative.

The event will only fire when the element comes in to view of the viewport, and out of view. It won't keep firing if the user scrolls and the element remains in view.

Bear in mind if you think the element may already be in view, you may need to kick the scroll event using $(window).trigger('checkInView'). If you include this plugin last (i.e., after you've hooked in to the event) then the script will automatically trigger the kick for you; thus, sending the event to your bound element.

The variable after the event argument indicates the visible state in the viewport. The third variable (topOrBottomOrBoth) detects which part of viewport is visible to the user.

$('div').bind('inview', function (event, visible, topOrBottomOrBoth) {
  if (visible == true) {
    // element is now visible in the viewport
    if (topOrBottomOrBoth == 'top') {
      // top part of element is visible
    } else if (topOrBottomOrBoth == 'bottom') {
      // bottom part of element is visible
    } else {
      // whole part of element is visible
    }
  } else {
    // element has gone out of viewport
  }
});

To stop listening for the event - simply unbind:

$('div').unbind('inview');

Remember you can also bind once:

$('div').one('inview', fn);

More complex example

This way we can attach inView to some DIV in our code to, for example, detect when it FULLY readed by user (user sees it's bottom and top) and only after 1 seconds of view, so after we call some out stats function or whatever:

$(someMyOneDiv).bind('inview', function(e, v, t) {
  var o = $(this);

  if(o.data('inviewtimer')) {
    clearTimeout(o.data('inviewtimer'));
    o.removeData('inviewtimer');
  }

  if(v) {
    o.data('inviewtimer', setTimeout(function() {
      if(t == 'top') {
        o.data('seenTop', true);
      } else if(t == 'bottom') {
        o.data('seenBottom', true);
      } else {
        o.data('seenTop', true);
        o.data('seenBottom', true);
      }

      if(o.data('seenTop') && o.data('seenBottom')) {
        o.unbind('inview');
        // here we will do WHAT WHE NEED (for ex. Call Ajax stats collector)
        // ...
      }
    }, 1000));
  }
});

Maybe there's a way to do this more elegant. And someone needed to test this on IE6-7-8 (they're nasty).

How it works

When the window is scrolled, the event checks the position of the elements against the viewport height and the scrollTop position.

However, I wanted to create a utility that would only check the elements that were registered under the 'inview' event, i.e. I didn't want to keep checking the element list if we unbind from the event.

This is achieved by dipping in to the $.cache store within jQuery, and looping through, looking for the elements tied to the 'inview' event.

This way the user can treat it like a native event on the page.

Offset Feature

If you decide to use this code for lazy loading images, you might be interested in preloading the image when it's getting close to entering the viewport. To do this, you can now add a data-offset attribute to your target element. For example:

<img data-offset="300">

or in JavaScript:

$('img').attr('data-offset', 300);

This allows the image to preload as it approaches the viewport so there's a better chance it will complete before the user even sees it.