> iScroll 5 ready for beta test

After a long development phase iScroll 5 is finally out and is looking for beta testers. This is probably the most important iScroll release yet as it leaves the mobile-only realm to become a universal javascript scroller.

iScroll was born in 2008 to fill the lack of native scrolling in the mobile webkit (at the time iPhone only) browser.

Time has passed, mobile browsers are getting better and a javascript scroller is becoming less relevant. That’s the reason why iScroll is not just a scroller for mobile anymore but a cross browser solution to interact with DOM elements. It now supports not only touch events but also pointers, key presses, remote controls and of course the good old mouse.

iScroll now runs on a wide variety of devices from desktop to mobile, from tablet to webtv. Some platforms need some tweaking though and this is were I need your help and the reason for the nasty beta notation.

Go get iScroll 5 beta 1!

Important changes

v5 is not a drop in replacement for v4. The core mission changed and with it the API. Hopefully the migration won’t be too painful.

The first notable difference is that the object is now called IScroll (capital I) instead of iScroll (lower i), so to invoke a new instance you’d do like so:

var scroller = new IScroll('#id');

This has been long disputed and at the end I decided to do things right and capitalize the class.

Another important change is that the horizontal scroll is always disabled by default. If you want to scroll horizontally you have to explicitly set the option scrollX: true. This should help preserve some precious resources.

You’ll also notice that the momentum formula now feels more natural and performance drastically improved. I did my best to optimize the script on Android and I believe that we are now pretty close to the best the device can offer.

Lastly, to hook to one of the many custom events (eg: onScroll) you no longer pass a function within the options but you use the on(type, fn) method. Eg:

var scroller = new IScroll('#id');
scroller.on('scrollStart', function () { console.log('scroll started'); });

This should be enough to get you started, now it’s…

… Demo time!

There are more new features than a blog post could host. I’m working on a detailed documentation and on more demos, but I need your help to remove the word “beta.1″ from the revision number.

The following are some of the demos I’d like you to test. Please report bugs on github or –if you are really lazy– send me a tweet.

Simple demo, to test the new momentum formula and augmented performace.

Custom easing functions. Try to pull down and release, or scroll down to the bottom.

Carousel with indicators, no additional code required

Horizontal iScroll preserving native vertical scroll (!)

Scroll with the keyboard

Minimap, you can scroll the detail view or the minimap itself

Parallax like there’s no tomorrow

Real time position probing

Scroll to element


Please note that more demos awaits you. Download the iScroll and try ‘em all.

What the CLA!?

CLA stands for Contributor License Agreement, it basically says that all contributions to the script are released to the author (me in this case). This might look Nazi, but it’s actually the only way to ensure that the script will remain free and open source for the time being.

I’ve been contacted by various entities (even open source projects) that without a CLA couldn’t use the script, so I decided to give it a shot hoping that it won’t damage the script development.

To send pull requests you are required to sign an online form. Sorry about that, I hate this stuff as much as you do but we live in a nasty nasty world.

The future

This is only the beginning. First step is to exit beta phase then I’ll work on detailed documentation and on some new features such as Infinite Scrolling.

Waiting for suggestions and bug reports.

/Share the joy


    • Author: EricB
    • Posted on: 2013/07/31
    • At: 03:47

    It’s possible to use “myscroll.refresh();” on iscroll 5?

    • Author: Jake
    • Posted on: 2013/07/31
    • At: 04:44

    Hi Matteo,

    I am currently using iscroll v4. But I’ve got an issue with using iscroll on page having form elements. It has a very weird behavior. The form is jumping in and out. Does this issue already been solved in v5?

    Great work though. Thanks

    • Author: André Silva
    • Posted on: 2013/08/01
    • At: 22:30

    How can i use IScroll with requirejs and backbone? anyone can help with this pls….

    • Author: Jay
    • Posted on: 2013/08/09
    • At: 12:22

    First of all: great job! I’m using v5 in our jQM 1.3.2 project for a right hand panel with responsive design; works wonderful!

    I just miss one behaviour I appreciated in v4, i.e. the scrollbar shrinking when scrollin “over the top/bottom”.
    1) is it possible in v5?
    2) is it possible to let the scrollbars disappear when finished scrolling and let it appear when start scrolling?

    Thanks for sharing your work with us ;>

    • Author: Rick
    • Posted on: 2013/08/14
    • At: 13:13

    Hi Matteo,

    Is there any way of setting eventPassthrough or scrollX / scrollY to false on an initialized instance of the iScroll object, rather than having to re-init the object? I ask because I want to open a large content block inside the iScroll element (which pushes other content to new X/Y positions) and I don’t want to reset the pages array…


    • Author: Nikhil
    • Posted on: 2013/09/24
    • At: 11:41

    Hi Matteo
    Just wanted to know whether iscroll works on Windows phones and tablets.

    • Author: Pacool
    • Posted on: 2013/09/25
    • At: 19:11

    GREAT JOB!!!! When are ready the infinity scroll?

    • Author: Rene Schade
    • Posted on: 2013/10/01
    • At: 13:46

    Hi! What is the status about the current beta? is it still beta 1? what are the plans for a stable release?

  • I am building a what’s on in my local area app and Its pretty much done apart from a little buggy thing to do with the horizontal scoll I’ve implimented using Iscroll5.

    I have several horizontal iscroll bars on a page and they work great until I try to scroll the page up and down on touch screen.

    If I try to scroll up and down when my finger is on an Iscroll section it will only go left and right.

    Any ideas of how I can scroll up and down as well as right and left when on an Iscroll element.

    the effect I’m going for can be seen in the BBC news App.

    • Author: Abhimanyu Singh
    • Posted on: 2015/10/24
    • At: 06:48

    i want to use snap: true on infinite horizontal scroll and different row height on vertical. Is it possible on IScroll 5?


/Leave a reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>