jQuery wrapper for iScroll

Matteo Spinelli did a terrific job writing a Javascript library that allows scrolling the content of a DIV element on iPhone and Android web browsers. The library is well documented in his site http://cubiq.org/iscroll. I don’t think that it is a must-have but I find very comfortable to implement functionality in a consistent way. Since I am a big jQuery fan I decided to wrap Matteo’s library in a very simple jQuery plugin.

(function($){
    $.fn.iscroll = function(options){
        if(this.data('iScrollReady') == null){
            var that = this;
            var options =  $.extend({}, options);
                options.onScrollEnd = function(){
                    that.triggerHandler('onScrollEnd', [this]);
                };
            arguments.callee.object  = new iScroll(this.get(0), options);
            // NOTE: for some reason in a complex page the plugin does not register
            // the size of the element. This will fix that in the meantime.
            setTimeout(function(scroller){
                scroller.refresh();
            }, 1000, arguments.callee.object);
            this.data('iScrollReady', true);
        }else{
            arguments.callee.object.refresh();
        }
        return arguments.callee.object;
    };
})(jQuery);

(function($){
    $.fn.iscroll = function(options){
		if(this.data('iScrollReady') == null){
			var that = this;
            var options =  $.extend({}, options);
				options.onScrollEnd = function(){
					that.triggerHandler('onScrollEnd', [this]);
				};
			arguments.callee.object  = new iScroll(this.get(0), options);
			// NOTE: for some reason in a complex page the plugin does not register
			// the size of the element. This will fix that in the meantime.
			setTimeout(function(scroller){
				scroller.refresh();
			}, 1000, arguments.callee.object);
			this.data('iScrollReady', true);
		}else{
			arguments.callee.object.refresh();
		}
		return arguments.callee.object;
	};
})(jQuery);

Basically you can use jQuery to select the content that you want to scroll and call ‘.iscroll()’ to add the behavior. If you need to overwrite the default parameters you pass an object with values that you wish to change. Here is an example of how to implement this:

$(function(){
    var elem = $('#content');
        elem.iscroll();
        elem.bind('onScrollEnd', function(e, iscroll){
            alert($(this).attr('id') +' - '+ iscroll);
        });
});

$(function(){
	var elem = $('#content');
		elem.iscroll();
		elem.bind('onScrollEnd', function(e, iscroll){
			alert($(this).attr('id') +' - '+ iscroll);
		});
});

Downloads

Download iScroll Libary
Download the iScroll jQuery Wrapper

When you call .iscroll() the library will find the parent element and make the content scrollable. This method will also return an instance of the iScroll class. If the method is called again it will refresh the content. This is convenient in case you modify the content dynamically (iScroll allows to detech DOM changes automatically).

The library dispatches an event name onScrollEnd when the scroll action is completed. In touch screen devices this library adds momentum. This means that the content will continue moving for a short time after the touchend event. By default the version 3.7 accepts a callback function that is trigger at the end of the animation. The wrapper overwrites the parameter and triggers a jQuery event instead. This approach will allow multiple callback functions.

By: Raul Sanchez
Category: Web Technology
Posted on: Tuesday, January 24, 2012

Not registered? Create an Account.

Lost your password? Click here to recover.

7 comment

JQuery wrapper for iScroll | Ajax | Syngu Sunday 19th, February 2012 - 06:51:08 AM

[...] Use jQuery iScroll to scroll the content inside a DIV. Register touch event listener as weel as a new onScrollEnd event Ajax Read the original post on DZone... [...]

jQuery wrapper for iScroll | Appcropolis - Web 2.0 BLOG | Web 2.0 BLOG Saturday 18th, August 2012 - 08:07:15 AM

[...] here to see the original: jQuery wrapper for iScroll | Appcropolis Bookmark on Delicious Digg this post Recommend on Facebook share via Reddit Share with Stumblers [...]

Nico Prat Friday 23rd, November 2012 - 12:05:46 AM

Nice ! I'd just add a simple : if( $(this).size() ) { ... your code ... } in order to avoid errors if I'd do something like : $('.iscroll').iscroll(); when there're no element selected. Thanks anyway.

Bob Newton Friday 17th, May 2013 - 11:22:14 PM

Hello, Very nice. I got it working, but I was actually interested in applying not just the scroll, but also the pinch/zoom on a single element or several different elements (pngs) on different pages. Is there any way to do this? I'm using jQuery Mobile/phonegap. Thank you for any help.

sanraul Thursday 23rd, May 2013 - 04:14:47 AM

This article only cover the integration with iScroll, but pinch/zoom sound like a good material for a different post.

Jo H Friday 24th, May 2013 - 08:12:23 PM

Hi sanraul, What i have is a main html and in a div i load an external html with the iscroll content... I'm able to get it working on any browser for desktop with your code but when i try it on my Ipod with ios 4.2.1 it is not working. My main html: $("#btn_clients").click(function(){ $('#clients').load('iscroll/iscroll.html', function() { $('#btn_clients').hide(); }); }); _____________________________________________ my external file : $(function(){ var elem = $('#container_logos'); elem.iscroll(); elem.bind('onScrollEnd', function(e, iscroll){ //alert($(this).attr('id') +' - '+ iscroll); }); }); So as i said this works well on desktop browser but not on mobile. If you have some time i'd really like to have your opinion and suggestions on that thanks.

Jo H Friday 24th, May 2013 - 09:12:11 PM

I just found out that i had to refresh the scroll from my main html. This code did the trick: setTimeout(function () { myScroll = new iScroll('musicwrapper', { hScrollbar: false, vScrollbar: false, checkDOMChange:false }); myScroll.refresh(); }, 100); Thank you so much sanraul