Matteo Spinelli's

iScroll finally received a complete rewrite. Now it’s smoother than ever and adds some new important features: pinch/zoom, pull down to refresh, snap to elements and more custom events for a higher level of hackability.

• Download
• Screencast
• Live Demo
• GitHub
• Forum

Project info

Last code update: 2011.07.03 – v4.1.7
Device compatibility: iPhone/Ipod touch >=3.1.1, iPad >=3.2, Android >=1.6, Desktop Webkit, Firefox, Opera desktop/mobile.
Discussion group
QR Code opens demo page.

Support development

If this script saved your day and you wish to support future developments you may consider sending some funds via PayPal or Flattr.

Overview

iScroll 4 is a complete rewrite of the original iScroll code. The script development began because mobile webkit (on iPhone, iPad, Android) does not provide a native way to scroll content inside a fixed width/height element. This unfortunate situation prevents any web-app to have a position:absolute header and/or footer and a scrolling central area for contents.

While latest Android revisions are supporting this functionality (although support is not optimal), Apple seems reluctant to add one finger scrolling to divs.

In addition to all previous iScroll features, version 4 introduces:

• Pinch / Zoom
• Pull up/down to refresh
• Improved speed and momentum
• Snap to element
• Customizable scrollbars

Please note that iScroll 4 is not a drop-in replacement for iScroll 3. The APIs have changed.

Also consider that the script is still in beta, and some APIs may slightly change.

Getting started

In the archive you’ll find plenty of examples to get you started. Before asking for help, please, look at the demos and read through all this document. I know it’s boring, but it holds all the secrets of the iScroll Ninja.

iScroll needs to be initialized for each scrolling area you need. There’s no limit to the number of iScrolls you can have on any single page, if not that imposed by the device memory/cpu. The type and length of the contents influence the number of iScrolls you can use simultaneously.

Try to keep the DOM structure as simple as possible, remove all the unnecessary tags and avoid too many nested elements.

The optimal iScroll structure is:

<div id="wrapper">
	<ul>
		<li></li>
		...
		...
	</ul>
</div>

In this example the UL element will be scrolled. The iScroll must be applied to the wrapper of the scrolling area.

Important: only the first child of the wrapper element will be scrolled. If you need more elements inside the scroller you may use the following structure:

<div id="wrapper">
	<div id="scroller">
		<ul>
			<li></li>
			...
			...
		</ul>

		<ul>
			<li></li>
			...
			...
		</ul>
	</div>
</div>

In this example the scroller element will be scrolled (together with the two ULs).

iScroll be must instantiated (ie: called for the first time) when the DOM is ready. You have mainly four options:

• onDOMContentLoaded event
• onLoad event
• inline, place the code below the html bit you want to scroll

onDOMContentLoaded

If you have only text and all images have fixed dimensions (ie: explicit width/height) you may use the DOMContentLoaded event.

In the document HEAD add:

<script type="application/javascript" src="/img/spacer.gif"> 
Note that the myScroll variable is global, so that you can access all the scroller functions from anywhere.
onLoad
Sometimes the DOMContentLoaded is a bit hasty and get fired when the contents are not ready. If you slip into some weird behaviors (eg: rubber band effect), try the following:
<script type="application/javascript" src="/img/spacer.gif"> 
In this case iScroll is started only 100ms after the page is completely loaded (graphics included). This is probably the safest way to call the iScroll.
Inline initialization
With this method the iScroll is instantiated as soon as the wrapper and its contents are written to the page. I wouldn’t suggest this approach, but I see many javascript gurus using it… so who am I to disagree?
First of all include the iscroll.js in the page HEAD and then create the iScroll object just below the scroller.
<div id="wrapper">
	<ul>
		<li></li>
		...
		...
	</ul>
</div>

<script type="text/javascript">
var myScroll = new iScroll('wrapper');
</script>

Alternatively you may use your preferred framework ready function (eg:jquery ready()).
Passing parameters to the iScroll
iScroll behavior can be customized with the optional second parameter. Eg:
<script type="text/javascript">
var myScroll = new iScroll('wrapper', { hScrollbar: false, vScrollbar: false });
</script>

The second parameter is always an object. In the example above the scroller won’t show the scrollbars. The most common options you will use are:

hScroll, used to disable the horizontal scrolling no matter what. By default you can pan both horizontally and vertically, by setting this parameter to false you may prevent horizontal scroll even if contents exceed the wrapper.
vScroll, same as above for vertical scroll.
hScrollbar, set this to false to prevent the horizontal scrollbar to appear.
vScrollbar, same as above for vertical scrollbar.
fixedScrollbar, on iOS the scrollbar shrinks when you drag over the scroller boundaries. Setting this to true prevents the scrollbar to move outside the visible area (as per Android). Default: true on Android, false on iOS.
fadeScrollbar, set to false to have the scrollbars just disappear without the fade effect.
hideScrollbar, the scrollbars fade away when there’s no user interaction. You may want to have them always visible. Default: true.
bounce, enable/disable bouncing outside of the boundaries. Default: true.
momentum, enable/disable inertia. Default: true. Useful if you want to save resources.
lockDirection, when you start dragging on one axis the other is locked and you can keep dragging only in two directions (up/down or left/right). You may remove the direction locking by setting this parameter to false.

Tips: to preserve resources try to remove the scrollbars (h/vScrollbar option).
Pull to refresh
 
'Pull to refresh' demo
This feature has become famous thanks to the Twitter app and many other native applications on the Apple Store. You can watch a preview in this screencast.
I’ve recently removed the “pull to refresh” from the script core and replicated the same functionality as an external plugin. Please have a look at the included example to get an idea of how it works.
All you have to do is to customize the pullDownAction() function. You’ll probably need an ajax call that loads new contents, remember to call the refresh method once the new data is attached to the DOM. Also please note that the example adds a 1 second delay to simulate network congestion. Of course you don’t want it in production, so remember to remove the setTimeout.
Pinch / Zoom
 
'Zoom' example
Let’s face it: scrolling is boring. That’s why iScroll 4 lets you also zoom in and out. By setting the zoom option to true the scroller reacts to pinch/zoom gestures. Believe your eyes if you don’t believe me.
Double tap to zoom in/out is also supported.
The minimum setup to activate zooming is:

var myScroll = new iScroll('wrapper', { zoom: true });.
You may further customize the zoom behavior with the following option:

zoomMax, this is the maximum allowed scale. Defaulted to 4, it means 4 times the original size.

Tip: to have good looking zoomed images place them into the hardware compositing layer. Or –to speak in plain English– apply -webkit-transform:translate3d(0,0,0) to all images that need to be scaled. Important: hardware acceleration takes a lot of resources, use it sparingly or your app will just crash. Don’t say I didn’t warn you.
Snap and snap to element
 
'Carousel' demo
The snap feature locks the scroller to predefined positions. This can be used to create fancy carousels.
By default iScroll subdivides the scroller into quadrants or pages of the same size of the wrapper. iScroll 4 also adds the option to snap to any element inside the scroller regardless of the wrapper size.
If you wish to create carousels I suggest to use the default “quadrant” subdivision. The perfect setup is:
var myScroll = new iScroll('wrapper', {
	snap: true,
	momentum: false,
	hScrollbar: false,
	vScrollbar: false });

To snap to elements, pass a string representing the query of the DOM elements the scroller should snap to. Eg:
var myScroll = new iScroll('wrapper', {
	snap: 'li',
	momentum: false,
	hScrollbar: false,
	vScrollbar: false });

In this example the scroller will snap to the top left corner of all LI elements inside the scroller.
Note that the snap string is applied to the scroller (ie: scroller.querySelectorAll(snap_string)), so '#scroller li' is wrong, while just 'li' is correct.
Custom scrollbars
 
'Custom scrollbars' demo
You can now customize the scrollbars appearance with a bunch of CSS. To apply a class to the scrollbars you just need to pass the scrollbarClass option:

myScroll = new iScroll('wrapper', { scrollbarClass: 'myScrollbar' });.
In this example the myScrollbarH class will be applied to horizontal bar and myScrollbarV to the vertical bar. Note that the scrollbar is composed by two elements: container and indicator. The container has the same height of the scroller wrapper, while the indicator is the scrollbar itself.
The scrollbar HTML structure:
<div>
	<div></div>
</div>

How to style it:
.myScrollbarV {
	position:absolute;
	z-index:100;
	px;bottom:7px;top:2px;right:1px
}

.myScrollbarV > div {
	position:absolute;
	z-index:100;
	%;

	/* The following is probably what you want to customize */
	background:-webkit-gradient(linear, 0 0, 100% 0, from(#f00), to(#900));
	border:1px solid #800;
	-webkit-background-clip:padding-box;
	-webkit-box-sizing:border-box;
	-webkit-border-radius:4px;
	-webkit-box-shadow:inset 1px 1px 0 rgba(255,255,255,0.5);
}

Have a look at the demo CSS to get an idea.
Public methods
iScroll has some public methods you can access any time to interact with the scroller. The most important of all is refresh, it must be called each time the content inside the scroller changes.
Public methods are accessed thank to the global variable used to instantiate the iScroll. In the examples I used myScroll, so you can access all the methods with: myScroll.name_of_the_function(parameters).
Continue reading for more details.
Mastering the refresh() method
iScroll needs to know the correct dimensions of both the wrapper and the scroller. They are computed the first time at start up but if your code changes the elements size, iScroll needs to be warned that you are messing with the DOM.
This is achieved by calling the refresh function with the right timing. Please follow me closely, understanding this will save you hours of scrolling frustration.
Every time you change elements height/width or you modify the html structure in any way (eg: appendChild or innerHTML) the browser renderer updates the page. Once the browser applied the changes you can access the new DOM (and properties) from javascript again. Sometimes this process is not instant.
To ensure that javascript gets the updated parameters you can force reading the DOM in a new instance. Look at the following code:
ajax('page.php', onCompletion);

function onCompletion () {
	// Here modify the DOM in any way, eg: by adding LIs to the scroller UL

	setTimeout(function () {
		myScroll.refresh();
	}, 0);
};

Here we placed the refresh call into a zero timeout, doing so we gave the browser the time to refresh itself and the new element dimensions are correctly taken. There are other ways to ensure the browser actually updated the DOM, but so far the zero-timeout has proven to be the most solid.
So the golden rule is: if unsure call the refresh inside a timeout.
Javascript scrolling
You can scroll programmatically with scrollTo, scrollToElement and scrollToPage (if your are using the snap feature).
scrollTo(x, y, time, relative) scrolls the wrapper contents to the x/y coordinates in a give timeframe: myScroll.scrollTo(0, -100, 200) position the scroller 100 pixels down in the wrapper within 200 milliseconds.
You can also scroll relatively to the current location by passing the forth parameter: myScroll.scrollTo(0, 10, 200, true). The scroller is shifter by 10 pixels in the y axis starting from the current location.
scrollToElement(element, time) scrolls to any element inside the scrolling area: myScroll.scrollToElement('li:nth-child(10)', 100). This code scrolls to the 10th element in the list. The first parameter is a CSS3 selector or the element node itself.
If snap is active you can also use the snapToPage(pageX, pageY, time) function: myScroll.scrollToPage(1, 0, 200). This will position to the second horizontal page in 200 ms. Pages are zero based (ie: page 1 is 0, page 2 is 1, …).
Destroy!
To completely destroy the iScroll and free some (a lot of) memory, call the destroy() method.
Best way to destroy an iScroll:
myScroll.destroy();
myScroll = null;

iScroll Lite Edition
iScroll is evolving and adding many new features to the basic scrolling functionality. If all you need is the plain old scroller for mobile webkit, you should really use iscroll-lite.js instead.
iScroll Lite is a frippery free version of iScroll 4. It supports scrolling on mobile devices only (no desktop compatibility). Snap, zoom, pull to refresh and superpowers are all stripped away. Fat free, eat as much as you can.
Known issues and future development
The followings are known issues I’m currently working on:

Form fields compatibility
Zoom glitches
Better desktop browser compatibility
onScroll event
hash and hash change support (ie: example.com/#element-id)
automatic refresh upon DOM change

Credits
iScroll is evolving thank to the help of all those who sent suggestions, bug reports and ideas on github, here on my blog and googlecode. This is by no means the work of a sole man.
In pure rnd() order: beedesk, Daniel J. Pinter, Aseem Kishore, Alex Gibson, Christoph Pojer, Shimon Dookdin, Will Bailey, Aaron Infidel. (Let me know if I forgot your name).
All those who supported, linked, loved the iScroll.
Projects using/based/inspired by the iScroll library
Please let me know if you are aware of any other project using iScroll.

Apple is using iScroll for carousels
appML
Snapr seems to be using iscroll for their Capture the Flag game
Chocolatechip-ui
HTML 4 & 5: The Complete Reference is based on iScroll
DataZombie’s jQTouch fork
Katie and the Witch’s Swap native app is using iScroll
Magic jQuery
Piggy is a web-app that provides mobile access to view sales data for your WP E-Commerce powered WordPress website
Playboy, the iPad version is based on iScroll
Readable the world’s first web page scroller with face detection.
touch-scroll jQuery plugin
Wobook magazine maker

Comments and Support
The blog comments reveled an inadequate system to discuss iScroll features, please use the google discussion group instead.