> Scrolling div for mobile webkit turns 3


I’m pleased that my original iScroll was useful to many. In the past months I received dozens emails asking for new features and bug fixes. I think it’s time to start developing a new version of the scrolling div for mobile webkit with added functionalities.

I recently modified the structure of the blog to have easier access to my projects. The iScroll has now a dedicated page, please head to the iScroll project page to get the lastest updates.

I’ve been asked to publish a new version of iScroll even if in development phase. Here you have it, but keep in mind that we are in Alpha1, the script is very rough and not ready for production. Okay, we are finally out of alpha and I’m moderately proud to introduce Beta phase. Please consider that I’m now working on GhostTouch, a framework dedicated and optimized to touch enabled mobile devices. The iScroll is a stand alone version of the scroller I’m developing for GhostTouch.

First things first. iScroll was born because mobile webkit (iPhone and iPod touch mainly, but also Android and Pre) does not provide a native way to scroll inside a fixed dimensions overflow:scroll|hidden|auto element. This unfortunate situation prevents any web-app to have a fixed header and/or footer and a scrolling central area.

Luckily mobile webkit offers a powerful set of hardware accelerated css properties that can be used to simulate the missing functionality, so the iScroll development has started… But there’s no rose without thorn. Making the scroll feel native has proven more difficult than expected. Version 2.x of the script was good enough, but it was lacking a lot of features.

Enough blabbing. Have a look at the screencast I baked for you or point your mobile device to cubiq.org/dropbox/iscroll.

Update 2010/05/06 – 3.1 beta 1: The most requested feature has been finally added. When new content is added or removed from the scrolling area (eg: ajax calls) iScroll automatically sets the correct position to comfortably host the new contents. We are still in beta, please give feedback.

How to use

All you need to do is to initialize iScroll with something like: myScroll = new iScroll('id');, where id is the #id of the element that will be scrolled. You can place it on window.onload or document.DOMContentLoaded.

iScroll automatically detects if you need vertical, horizontal or both scrollbars, but you can force scrollbars hiding with the optional second parameter. Eg: myScroll = new iScroll('id', {vScrollBar: false, hScrollBar: false}); (this prevents both scrollbars to appear).

On orientation change iScroll also refreshes itself and detects if the scrolling area has changed in size. You should add your code to resize the elements on orientationChange as shown in the example.

Other considerations

I decided to remove the scrollbar shrinking effect (ie: when you scroll outside of the screen the scrollbars reduce in size). Can be done with little effort and some frameworks already implement it, but it’s an inconsiderate waste of resources –precious resources– for such a small feature.

The script should now work on Android, too (at least on version 2.1, please give feedback).

The momentum formula I’m using feels pretty natural, I use a completely rewritten (and ridiculously simple) algorithm. If deceleration doesn’t look natural to you, you can try to tweak friction and deceleration parameters on line 273 and 274.
Q: Why aren’t you adding feature X?
A: I’d like the script to work on older devices. Not everyone has a SnapDragon ;) Plus, I’d like to keep this script as bare bone as possible so it’s easier for you to customize it to your needs.

Q: I’ve developed feature X, may I send it to you? Will you add my code to your script?
A: Please do! It’s not guaranteed that I will add your feature to the script, but I’ll review all code you send to me (matteo [at] this domain). Consider that scripts will be released under MIT license, if this is a no-go for you, don’t send.

Q: I’m in a hurry and I need feature X to be added to your script ASAP. Can you help me?
A: Have you considered hiring me? (matteo [at] this domain)

Go to iScroll project page

/Share the joy


    • Author: James
    • Posted on: 2010/05/14
    • At: 14:54

    @Eli: That is a good description of what I am experiencing. I did try to change the translate3d’s to translates as stated in the post #134 to see if that would help, and it slowed scrolling down to a crawl.

    @Matteo: Whenever I scroll, it always pauses before scrolling, and it really doesn’t take much of a gesture to have the screen fly to the top or bottom of the scroll height.

    If you have an iPad to play with, I can setup you up with a link and login so you can see what we are referring to.

  • @James: is this behavior restricted to ipad? does it work properly on the emulator? If you have a demo ready, please send me the url by email. Thanks.

    • Author: Terry
    • Posted on: 2010/05/17
    • At: 06:55


    I have textbox at the footer. On Iphone, when I click on footer, the header doesn’t remain fix but moves up the screen. Is it the issue I am having or is it a bug?

    • Author: Terry
    • Posted on: 2010/05/17
    • At: 09:31


    I will appreciate if you could provide the change in script that makes it possible for footer to align itself in both portrait and landscape position.

    • Author: James
    • Posted on: 2010/05/17
    • At: 16:22

    @Terry: I have footers on my pages and don’t have any issue with them aligning when changing back and fourth from landscape to portrait. For proper scaling, make sure NOT to include the meta tag that forces the scale to 1.0: .

    • Author: John
    • Posted on: 2010/05/19
    • At: 05:10

    Any way to get select boxes working?

    • Author: Terry
    • Posted on: 2010/05/19
    • At: 07:47


    Thanks for the response. I have chat thing working with header having the name of the other person. I want header to be fix at all times. The footer should remain at bottom and fix at all times. Now what happens is that when I click on textbox in footer, Iphone keyboard moves everything up as it does in normal page. Hence, the header does not remain fix.

    Need help in this!

  • I think you should specifically state that div.scroller and div.wrapper – or the element that scrolls and its parent for that matter – need to have:

    padding: 0;
    margin: 0;

    If not the viewport becomes that amount of pixels off after an orientationchange event. Or it should be fixed somehow in the refresh() method, I’ve been looking into it but could not find a fix asap.

    • Author: James
    • Posted on: 2010/05/19
    • At: 14:23

    @John: Refer to post #19.

  • Found that removing width – effectively defaulting it to ‘width: auto;’ – from the elements did the trick (also from #header and #footer). But on my a bit ancient iphone 3g I do experience some flickering when iscroll.js starts. I even added a setTimeout(startScroller, 2000); to be sure it is not the data I’m loading. It is probably related to my slow device since I’ve only seen one other poster mentioning this.

    Thanks a lot anyways.

    • Author: John
    • Posted on: 2010/05/19
    • At: 16:17


    As stated before, that solution does not fix the problem. It only disabled iscroll for the page the select element is in, thus enabling the select element but the scrolling ceases.

    • Author: John
    • Posted on: 2010/05/19
    • At: 19:07

    I tried the solution posted @19 and it works with the scrolling. Sorry for the confusion.

    • Author: John
    • Posted on: 2010/05/19
    • At: 22:40

    Here is a follow up to the drop down situation. Everything works fine except after the selectbox is selected and the iphone menu is brought which displays the select options – the scrolling region gets messed up. After selecting an option the content is scrolled all the way up and it is hard to reset it back to place. I will try looking at that code at handlevent and see if I can possibly add a myScroll.reset call in there?

  • @Terry: that is a know bug. A lot of hacks are needed to prevent that behavior, nothing that can be explained here in a comment. If you are in a hurry, you may consider hiring me, otherwise please wait until an official workaround is found and posted. I’m trying to make the script as flawless as possible, as soon as I find bug fixes I post them here.

    To all: Do you think we should open a google group for iscroll support?

    • Author: Terry
    • Posted on: 2010/05/20
    • At: 08:00

    Thanks Matteo! Yes I think group/forum will be a great initiative as comments are not a nice place for discussing bugs!

    I will contact you soon and discuss the project.


    • Author: John
    • Posted on: 2010/05/20
    • At: 18:18

    I’ll give $5 to the person who can fix the issue I am getting. After a select box is opened and the options appear at the bottom (iphone/ipod) the scroll content is pushed upward and then it is impossible to scroll to it. I tried using refresh() but no avail.

    • Author: shivraj
    • Posted on: 2010/05/21
    • At: 08:47

    I am using this framework for scroll, i have a prob using it in a jsp page where is form tag. when i use a form tag, the touch scroll disappears and normal tag appears on the page.

    Any help please

    • Author: Hernan
    • Posted on: 2010/05/21
    • At: 15:35

    Worked like a charm! Great!! many thanks!

    • Author: Paz
    • Posted on: 2010/05/24
    • At: 01:17

    Thank you so much for this fantastic script!

    I have limited JS knowledge but managed to get it to work. There’s only one problem. My #scroller contains a that is an accordion which opens a child after clicking on the . It does that with a jQuery slideUp() and slideDown() and works smoothly in Safari. On the iPhone the scroll experience is very jerky and jumps all over the place. I assume the jumping accordion is because of the animated change of height which happens in the #scroller and the generally jerky scrolling has something to do with rendering of the elements. There are only about 20 elements with a corresponding but they all use CSS gradients and rgba. Could that be the problem why the performance is so poor? Is there anything I can do?

    • Hard to say without looking at the code. Generally speaking jquery does not use HW accelerated functions, so that’s why the jerky accordion animations. Also alpha, shadows and gradients impact on performance.

      • Author: Paz
      • Posted on: 2010/05/25
      • At: 02:59

      Thanks for the quick reply. Have a look at http://bit.ly/clicheb

      Can you point me in the right direction how to improve this?

      Thanks a lot for your help!

    • 1) At the end of each slideDown/Up you have to call the iScroll refresh() function.
      2) You can’t use jquery for slidedown/up. I’m afraid you should develop your own hw accelerated accordion. Maybe I’ll work on something like that in the near future.

      • Author: Paz
      • Posted on: 2010/05/25
      • At: 12:30

      Thanks Matteo, I really appreciate your input!

      I tried to call the refresh function but it didn’t really change anything.

      I now tried using CSS transition, changing the class names onclick with jQuery. This gives me essentially a very basic accordion. (see http://bit.ly/clichec) It’s still very jerky even though the animation is achieved through CSS -webkit-transition and not jQuery. What am I doing wrong?

    • Author: David
    • Posted on: 2010/05/24
    • At: 23:19

    I am having an issue when there is a large amount of content in the #scroller div. Even if I set the height of the div to something ridiculous like 50000px, I can only scroll a little more than a page length before it bounces back.

    Thanks for your help in advance.

    • Have to try. It could be a hardware limit. Also check that the code inside the scroller is well formed xhtml.

    • Author: John
    • Posted on: 2010/05/25
    • At: 03:46

    I’m assuming there is no fix for the select box problem where the content in the scroller gets pushed upward.

    Emailed the author and no response

    • The only solution to the select box problem is to develop a html/js select box alternative. I’m working on it.

      (Sorry for not replying to all in a timely manner, I receive dozens emails every day)

    • Author: John
    • Posted on: 2010/05/25
    • At: 18:14

    Out of curiosity, is there a reason why the virtual keyboard (for typing in a input text field) does not screw up iscroll, however the select box options do.

    • welcome to my world of JS frustration :)

    • Author: John
    • Posted on: 2010/05/26
    • At: 22:21

    I am trying to find away the select box issue. For now I am trying to use radio boxes instead by using them as options and placing them in a height limited div to show only one at a time, and then have iscroll scroll that div to see the other radio buttons but I cannot figure out how to set up another iscroll within a iscroll ?

  • Discussion continues on iScroll Project Page where you’ll find the latest version of the script.