TouchScroll, a scrolling layer for WebKit mobile [update]

[Update 2010-09-17:] Check the new version.

Dion Almaer was faster than me blogging about TouchScroll. Here is what you are waiting for – the “official” blog post about TouchScroll and the link to the repository.

Here it is: TouchScroll, our scrolling layer for WebKit Mobile. It is JavaScript/CSS 3 based and allows for fixed elements like headers and toolbars on web pages when viewed on the iPhone or on Android. It works on the iPad, too. Check out the demo (short URL: to see it in action – it works in Desktop Safari (at least kind of) or WebKit Nightly (very good), but I recommend you have a look at it on your iPhone, iPad, or Android based device.


While Safari Mobile features native scrolling, there are two reasons to re-implement scrolling with JavaScript: The original scrolling behavior is rather slow – we were looking for a solution that feels more fluid. And the viewport behavior of Mobile Safari and other mobile browsers using WebKit doesn’t allow for fixed positioned elements. It is optimized for document reading, not for building interfaces.

Our goal is to be able to deploy application interfaces to browsers of handheld devices that feel as familiar as possible for the user. TouchScroll enables developers to use fixed interface elements like headers and toolbars.

We also use PhoneGap a lot to deploy cross-platform applications onto smartphones, and we think that web based apps don’t need to feel like aliens for users. And we weren’t satisfied with existing solutions.


To add a scrolling capabilities to an element, that element must have a fixed size. Have a look at the demo for an elegant approach using

display: -webkit-box



<div class="scroller"><!-- some great contents --></div>


var scrollNode = document.querySelector(".scroller"), options = {};
var scroller = new TouchScroll(scrollNode, options);

At the moment, the only known option is elastic. Use

{elastic: true}

as second parameter to add the bouncing effect to the scroller.

Get it!

TouchScroll is available on github. Feel free to fork it and send patches back. You can also get a minimized file that includes the css-bezier library that TouchScroll depends on.

How is it done?

TouchScroll uses a combination of JavaScript and CSS 3. All animations are done with CSS transitions – no JavaScript intervals.

The elasticity effect when crossing the scroller bounds is achieved by dividing the bezier curve (used as timing function) into two sub-curves using my (yet to be finished) CSS Bezier library for JavaScript.


TouchScroll allows you to customize many aspects of the scrolling behaviour: Have a look at the


object at the top of the source file.

Customizable properties include bouncing behaviour and deceleration animation. Feel free to experiment. I know that scrolling is not as close to <insert device of choice> as possible. If you think you’ve found better values, just let me know.

Configurable properties include:

  • Scrolling threshold: The minimum pixel amount needed to begin scrolling
  • Flicking behavior: flicking threshold, friction, and deceleration animation.
  • The elasticity/bouncing effect: factor and maximum bounce length.
  • Snap back behavior: timing function and default duration.


After instanciation, each TouchScroll scroller re-adapts to its contents after




events on


as well as after


events on the scroller itself. That means, the scroller adapts to content additions and deletions.


TouchScroll is meant to be used with touch-based devices and also works well with a stylus (tested with a Wacom tablet). Don’t use it for desktop browsers and the like. Simply add

overflow: auto

to the scroller element for these cases. Zero-cost compatibility.

Hiding and Showing

If a scroller is instanciated with an layer that is not beeing displayed, it needs to be refreshed manually after making it visible. Simply use the




TouchScroll inserts two more


elements to the outer scroller container, that wrao the prior contents. That means, that the outer scroller element must not have padding. The CSS child selector (

a &gt; b

) won’t work any more after instancing TouchScroll on an element for the same reason.


Android has several problems that need to be solved. If you have solutions, please keep in mind that TouchScroll should remain compatible with WebKit as found on Android 1.5 and send us a patch.

  • When not preventing the default action of the initial touchstart event on Android, the following touchmove events queue up and fire just before the eventual touchend event. That makes scrolling impossible.Cancelling the touchstart event results in other problems: It prevents tapped elements from beeing focused or clicked. The current workaround – dispatching a synthesized click event – hides the focus rectangle and makes the focussing of form elements nearly impossible, which is even worse.That means: at the moment it is not possible to use TouchScroll in conjunction with forms on Android.I’d like to know whether there is a solution that eliminates the need to prevent the default action of touchstart.
  • Due to the lack of hardware acceleration, the rendering performance on Android isn’t nearly as good as on the Apple’s devices. We already invested a lot of work to achieve good performance. If you can do better, send us a patch!
  • Support for
    -webkit-transform: matrix(…)

    is broken in Android < v2.0. That affects reading the computed style of elements. We already worked around that issue using a regex-based parsing function for those devices.

Other Devices

The browser of S60 devices is based on WebKit, too. However, apart from the fact that TouchScroll does not work on those devices, you should simply set the overflow style of the scroll container to

overflow: auto

for these devices and benefit from native scrolling. The same goes for Nokia WRT apps.

I’ve done a quick test on the Palm Pre. Unfortunately, TouchScroll does not work in the browser of webOS. Moreover, I’m not sure whether it actually makes sense in this particular browser, as its overlays would lie directly on top of fixed elements at the bottom. In webOS apps you should probably use the native scroller anyway. Maybe I’ll do a short tutorial on how to instanciate TouchScroll on iPhone/Android and the webOS scroller when deploying a cross platform app to all of those devices.

What other devices are relevant? Let us know!

To Do

The official to-do-list:

  • Keep the scrollbars round while bouncing – I already know how to do this, so you can expect the solution in the next days.
  • Add an option to completely switch off scrollbars.
  • Find a solution to the event problems on Android – help greatly appreciated!
  • Pingback: Ajaxian » TouchScroll: Implementing scroll physics in JS and CSS

  • http://Gucci JS

    Awesome work. I am currently working on a Dashboard-style application which uses a long widescreen-horizontal scrolling display, I’d love to know how I can integrate this for FF/Webkit browsers.


  • Matthias

    Really looks great. Could be a fix to Grubers biggest concern: that WebKit scrolling is slow.
    Do you have an explanation why native scrolling is slower that css transforms?

  • Nathan Borror

    I’ve been waiting for something like this and your implementation is close to native behavior. Why can’t you select text?

  • Nathan Borror

    I should clarify, why can’t you select text using the iPad? Looks like text selection works on the iPhone.

  • punkassjim

    This looks spectacular, and congratulations on your speedy recovery from being Fireballed!

    One thing to consider putting in your “known issues” file: find a way to allow default behavior when a user taps-and-holds on a link. The native context menus don’t work right now. This seems to be an issue with several of the pseudo-fixed-positioning JavaScript solutions I’ve seen. I would imagine it’s possible to refrain from sending the preventDefaults() command if the touch event a) doesn’t travel more than the 5px threshold within b) the standard amount of time it takes to trigger the default context menu.

  • punkassjim

    I should also note, I’m on iPhone 4.0b2 and I can’t select text either.

  • Pingback: Resources for iPhone and iPad Development « Damon Clinkscales

  • formasfunction

    I believe the parameter {elasticity: true} should instead be {elastic: true} as per the demo.

  • David Aurelio

    @JS: that should work out of the box for webkit browsers. The scroller is not (yet) compatible with FF/Gecko, although it would be possible. You need to provide an implementation of WebKitCSSMatrix (a constructor available in WebKit) and add support for different vendor prefixes. Do you want to use TouchScroll for desktop browsers? I wouldn’t recommend that.

  • David Aurelio

    @Nathan, @punkassjim: Thank you for pointing out those issues! Maybe I’ll have to do more code forking. Initially, I wasn’t preventDefault()’ing most events on the iPhone, but had to add it to get things working on Android. So maybe this can be solved easily if I can distinguish Apple’s devices from Android. I will add the issues you’ve found to the list.

  • David Aurelio

    @formasfunction: You are right. I just corrected the text. Thank you.

  • Pingback: TouchScroll, a Scrolling Layer for WebKit Mobile «

  • joscilene freitas

    você e mesmo Deved ENTÃO VOCÊ UM MEGA INTELIGENTE !!!!!!!!!!!!!!!!!!!!!!!!!!! UM GRANDE ABRAÇO

  • Gerben

    When you swipe your finger down, once you finger moves over the bottom toolbar its abruptly stops scrolling. While if you release your finger just before hitting the toolbar, it continues scrolling.
    You probably cant detect touches outside the viewport, but when a touch leaves the bottom of the viewport, at a certain speed, you can assume the user want the scrolling to continue, like safari does by default.

  • Jeff

    Thanks David. This is great.

    I have a question about how you did it. I am working on something similar, but am running into an issue. I’m using CSS transitions to scroll text on the iPad, but whenever I move the text (using CSS/translate) there’s a weird glitch in the beginning. Did you run into this, and if so, how did you overcome it?

  • order free magazines

    That was a superb article,You discover interesting things every day.

  • Pingback: links for 2010-04-29 // Aaron Gladders

  • Pingback: links for 2010-04-29 « Mandarine

  • David Aurelio

    @Gerben: Thank you. I know that problem, just didn’t remember to add it to the list of known issues. Do you know a way to detect that case? I’ve tried to find a way of detecting the finger leaving the viewport, but didn’t succeed yet.

    @Jeff I think I’m having a similar problem with TouchScroll – there is a short jump when scrolling down for the first time, before the contents outside the visible area are rendered (at least on the iPhone 3G). I’m not sure if it’s the same problem you are experiencing. You might also have to add “-webkit-transform-style: preserve-3d” to the element you are transforming. It solved many flickering problems for me.

  • Allen Pike

    You mentioned a dissatisfaction with existing solutions, which likely refers to the widely-used iScroll library ( Do you have any specific goals or features that are different from iScroll’s, or are you moreso dissatisfied with it at the code level? I’ve heard a few PhoneGap developers express discontent with iScroll, but to the extent I’ve played around with it I couldn’t determine what was wrong with it (other than that its scrollbars no longer shrink when bouncing.)

  • David Aurelio

    there is nothing “wrong” with iScroll – the reasons we wanted something different are:

    1) iScroll is not compatible with Android. The successor library – ghosttouch – seems to be in a very early development stage, and the example didn’t work on Android, either.

    2) I’m not sure about this one, but iScroll doesn’t seem to have that extra deceleration when flicking over the bounds.

    3) There have been only few updates to iScroll/ghosttouch in the last time.

    So, as long as you’re ok with iScroll, keep using it. There’s nothing wrong with it.

  • Erik Larsson

    This looks very promising, will have a go at it this weekend. Was using jqextension until now but might reconsider.

    I guess there’s no problem running it in fullscreen mode, using PhoneGap?


  • Jeff

    That totally solved it! Thank you David!!

  • Pingback: TouchScroll, a scrolling layer for WebKit mobile [update] « Uxebu … | Source code bank

  • Pingback: iPad Links: Friday, April 30, 2010 « Mike Cane's iPad Test

  • Pingback: Antipode – Scrolling libraries for Mobile Safari

  • Adam

    I’m in the early stages of app development and you have no idea how helpful this scrolling layer is going to be for my app. The demo is perfection for what I have been (unsuccessfully) trying to achieve myself. Thank you so much.

  • David Aurelio

    @Erik It has even less problems in fullscreen mode, because the event-absorbing bottom toolbar is missing. Regarding PhoneGap – *cough* – I have to admit I didn’t make a package yet. Should work flawlessly. If not, I will fix it, because we need it for a client project.

    @Jeff, @Adam Thank you. I’m glad you like it. Don’t forget to report the issues you run into on github!

  • timpeti

    It seems you cannot have a div within a website using touchscroll while the rest of the page uses native scrolling, right?
    Is it possible to have two nested touchscroll enabled divs independently scrollable?

  • David Aurelio

    @timpeti: That’s true at the moment, but I might consider re-organizing the event handling to make it possible if there are convincing use cases.

    Nested TouchScrollers should be possible in theory, but I’ve never tried. Simply try it and let me know whether it works!

  • Tim

    Is there a way to get event notification that a scroll has occurred within TouchScroll? Also, would need to get the absolute Y position of content being scrolled within the scroller. I’m trying to lazy load images within a list as user scrolls down w/ some pre-loading of the next n scroll window heights. I was doing this before by listening to the onscroll event on the document. I’m looking for a similar solution now that I have the content scrolling within TouchScroll. Any help would be appreciated.

  • Sy Naka

    I must be missing something fundamental but how do I get 2 touchscroll enabled divs working? Is this right? Looking to implement it for ipad project.

    HTML : 1st touchscroll div here 2nd touchscroll div here
    CSS: #one{float: left; width 300px;} #two{float:right; width:300px;} + demo.css

    Thanks muchly.

  • Sy Naka
  • David Aurelio

    @Tim: I will implement scroll events for TouchScroll – then you can simply use your existing solution.

    @Sy Naka: Do you instantiate TouchScroll with both divs? The demo.css is not needed, you need the touchscroll.css and the js file.

  • Sy Naka

    Excuse my js ignorance but is this referring to this bit of code:
    var scroller = new TouchScroll(document.querySelector(“.scroller”), {elastic: true});
    Clearly this line then doesn’t instantiate all instances of the scroller div. I’d appreciate a simple example how to do this to 2 divs. Many thanks.

  • Pingback: Around the web |

  • Sy Naka

    Thanks, worked it out. Just had to change/add the div class to the var scroller. Much appreciated again. Good work.

  • Neil

    This is a fantastic library. I’m using it with great success. In one part of my site the content changes dynamically, and I’d like the scroll position to jump back to the top. I can’t find a way to do this? How would you go about creating a “resetScrollTop” method?

  • David Aurelio

    @Sy Naka Glad it worked out. Thank you.

    @Neil: At the moment you can use “scroller.scrollTo(0, 0)” – on the scroller instance, not on the div element. I tried to capture changes to the “scrollTop/scrollLeft” properties of the div itself, but failed using “__defineSetter__”.

    @punkassjim: native context menus now work on the iPhone I’m testing with. I will push the changes to github and to the demo in an hour.

  • Tim

    David – Thanks for agreeing to add the scroll event, I’ll keep an eye out for revisions.

  • Vernon

    This a pretty cool project, but when you compare TouchScroll’s reflex animation (dragging the page down and then letting go), TouchScroll seems to be using an ease-in while iPhone OS applications seem to be using an ease-out.

    This gives the animation a really strange feel since generally the iPhone OS approach feels like the view is “snapping back,” while the TouchScroll approach doesn’t really seem to be mimicking any kind of physical phenomenon.

    Just my two cents :).

  • Mike

    Hey, I’m having a little bit of an issue with this, sometimes it will work fine, but other times the TouchScroll divs won’t work unless I rotate the iphone, then it will work fine!

    Is there any documentation to make sure I’m initialising it all correcly?


  • Shivraj


    I am using above mentioned framework for touch scroll implementation.

    There is a prob i am facing. for Example if there is a jsp/html with a tag in the page, the scroll doesn’t seem to work.

    Please help me out in this.

    Thanks a ton in advance.

  • Shivraj

    Sorry for the previous post..the correct one is here.

    I am using above mentioned framework for touch scroll implementation.

    There is a prob i am facing. for Example if there is a jsp/html with a tag in the page, the scroll doesn’t seem to work.

    Please help me out in this.

    Thanks a ton in advance.

  • Shivraj


    I am using above mentioned framework for touch scroll implementation.

    There is a prob i am facing. for Example if there is a jsp/html with a form tag in the page, the scroll doesn’t seem to work.

    Please help me out in this.

    Thanks a ton in advance.

  • David Aurelio

    @Vernon: The next release should have a better snap back animation. Thank you.

    @Shivraj: I do experience some problems with forms inside scrollers. i’m trying to fix this with the next releases. This shouldn’t depend on JSP.

  • shivraj

    Hi David,

    Actually i faced one more issue. when i scroll tag has a form tag, it doesn’t allow me to enter any values for the textbox or text areas. There seems to a kind of mask that is applied on the scroll section.

    But if through the js i can feed the values. i can do getElementById and do focus which is not possible through normal on the screen by click.


  • Carsten

    Hi David,
    I’m in early stage of development and in your readme you say “Simply add overflow: auto to the scroller” for developing on, as in my case, desktop safari.
    My problem is, that if I change the CSS to
    .scroller {

    overflow: auto;

    Safari crashes on reloading the page >_<
    Any ideas on this?

    Cheers /Carsten

  • Carsten

    Me again, some info on the topic. I can develop now as I have downloaded touchscroll.min.js again (new version?) and it works (sufficient) in safari.
    But overflow:auto still crashes the browser.
    Cheers /Carsten

  • Abraham


    I’m using phonegap and jqtouch for an app I’m developing, however when I declare your scroller my content is not visible. Any ideas?

  • David Aurelio

    @Shivraj: Thanks for reporting. I am currently experiencing a few problems with form elements within the scroller and hope I can fix them with the code rewrite I’m currently doing.

    @Carsten: Sounds like a problem with “display: -webkit-box” I’ve stumbled upon: When the children of the box exceed a height of 100%, Desktop Safari crashes. If I remember correctly, the solution is to set the flexible sub-box to “height: 1px” (it will expand and take up the rest of the space anyway). This bug is fixed in WebKit Nightly btw.

    @Abraham Does your scroller element have height? If it has, there has been a problem in a few situation with a specific version of touchscroll.css. Do you use the latest version?

  • Abraham

    Me again, I did define a height and width. It is now displaying after updating to the latest css. Now I have another problem however; when I scroll the flick to scroll doesn’t work and the scrolling stops as soon as my finger stops touching the screen and the scrollbar remains visible on the device. If i use safari it is almost as if I were still clicking because any mouse movement scrolls up or down.

    Any helps would be appreciated

  • David Aurelio

    Abraham, could you put an example online or send it by e-mail?

  • petcory


    Hi, i’v got a strange bug wich i don’t know how to reproduce, maybe you guys know?

    I’v got a list (classic iphone) list with albums. When i click on a album then i view the contents in another page wich is touchscroll enabled. The first tab (current) displays a grid view, while the second tab a list view. Know that works great, exept..sometimes i get to get scrolling in all directions (horizontal and vertical) -> i need it to stay only vertical.

    To eliminate some css bug possibilities i’v debugged it twice and i can’t figure it out why do i have sometimes (for some albums) multi-scrolling. (the code is the same so it should be like that)


  • petcory

    Where can i find the latest touchscroll production version:


    Wich contains the newest?


  • Carsten

    @Abraham: I had exactly that, too. For development use mac-desktop-safari-4+ (the standard setting under “developer”).
    Don’t switch to Mobile-Safari or whatever because then the desktop version doesn’t handle the TouchScroll very good.

  • Carsten

    @Abraham and @David:
    I correct myself: This bug happens for me when I use the touchscroll.js in src/ and when I use the touchscroll.min.js it’s working soso ok in desktop safari as mentioned above.

  • Abraham


    The reason for that is that the touchscroll.js doesn’t have the bezier class. If you are goign to use that one, simply download David’s bezier js (you can find it on github). If not, use the min which includes it already.
    I also found out that the performance was much better on the device itself than just safari.

  • Carsten

    Thanks, good that it’s my bad :) Plus, I use webkit-nightly now and deving/debugging is much much easier!

    I had an issues with TouchScroll and JQuery, when ajaxing in content and so, but founf a workaround:
    Glitch: Doubling of onclick=”" in residing in by calling setupScroller()

    The last issue I have is with forms inside of scrollers (what “shivraj” posted in comment#48). Is there a patch on the horizon?

  • Carsten

    Thanks, good that it’s my bad :) Plus, I use webkit-nightly now and deving/debugging is much much easier!

    I had an issues with TouchScroll and JQuery, when ajaxing in content and so, but founf a workaround:
    Glitch: Doubling of onclick=”" in [a href] residing in [div class="scroller"] by calling setupScroller().
    Workaround: [a href="" onclick="return false;" onmouseup="doSome();"]

    The last issue I have is with forms inside of scrollers (what “shivraj” posted in comment#48). Is there a patch on the horizon?

    (Sorry, for doublepost, htmltags broke the first one)

  • Pingback: Wolfgang.Schmidetzki.Net: Weitere Mobile-Safari Einschränkungen

  • pectory


    I’v got the same bug :))

    I’v put an alert inside my onclick function, and it is sometimes doubled!!

  • Gerry Straathof

    I am trying to understand the example that you have provided, but I cannot. I am trying something similar (multiple divs id’s/classes) that are hidden but that are scrollable once they are visible.

    They are not becoming visible through the use of a tab function such as in your example. In fact, some of them are becoming visible through the links that are inside a separate (originally invisible) scroller.

    How does one simply generate a scroll function and make it active on becoming visible. In simplified terms, please.

    An example of what I am working in is here:

    It is done using iscroll at teh moment, but that javascript isn’t what I would like for cross-device uses (and it limits the interaction of the links inside a scroller)

    Thank you.

  • Gerry Straathof

    (addendum) That site only works on iphone/ipodtouch at the moment (looks iffy on pc’s)

  • Andy


    First let me say this is a fantastic piece of code and has really helped in the implimentation of a web app I am building.

    We have a way for people to favorite listings in the scroll area, however if they are scrolled down on the page and they choose to show their favorites, if they are too far down the page all they see is a blank area and they need to scroll up to see their information.

    I looked through the code but could not find a scroll to top option.

    Do you have any ideas on this?



  • Abraham

    I have a scrollable list with an href=tel:xxxxxxxxx. I always declare a scroller regardless on the size of the list (the list is poopulated via ajax). However, when the content overflows my href link stops working, I can click (tap) on it and it doesn’t do anything. however, if the list is small enough, the hyperlink works fine and the device gives me the option to call, save number etc. Does anybody have any ideas or solutions to this?


  • Abraham


    What do you mean when the choose to see their favorites, does the view change, do you remove content in the list? Is that why users have to scroll up?

    If you actually remove content, why don’t you instead create another div and scroller that is presented (look at the touchScroll demo). That way the content will appear at the top regardless.

  • Carsten

    @Abraham: That seems to be the same glitch that prevents forms from working correctly. Did you have a look at my post#60?

    I mailed David my research and findings and atm I’m keeping my fingers crossed that David finds time to look into that very soon or else I would have to switch to something else :(

    @David: I begin phonegap implementation of my project tomorrow and if something behaves different when compiling with XCode I’ll let you know right away.

  • Andy


    Thanks for the reply,

    The content is being hidden in the div, rather than perform another query. As the div is pretty long, when it is hidden they may be scrolled down the page quite a way. If there was a back to top scroll that would be perfect.

    Otherwise I can look at performing a query against the DB to retrieve just the matching records.



  • Abraham


    There is currently no back to top scroll…You could do the query against the DB, or if you’re hiding content….or could you populate from the db two different div, one with all the content and the other with just the favorites and have one hidden while the other is visible and toggle those two, that way you only call your DB once?

  • Andy


    Now that’s an interesting idea. The problem now is we have added filters to the list, filtering the days and session tracks as well. I think that would add a little too much pre-processing time (especially as majority will be on iPad or iPhone)

    wondering now if there is a way that when elements hidden reset the parent div height to elements that remain.

    Ah, the things that trouble us late in the evening!!!



  • Abraham

    I am trying to use a scroller on a video list with , however they are fixed; they do not scroll. Has anybody run into this problem, does anybody have an idea on how to fix it?

  • Carsten

    I had the same prob with scrolling to top. For me it works like this:
    - The scroller is hidden and I’m about to load new content into it and show it
    - Call scrollers["myscroller"].scrollTo(0,0); on _before_ you load in new content

  • Erik

    I have a slight problem where the bottom tabbar is getting cropped when I view in the iPhone SIm, via phonegap (Text not showing, meanwhile if watching in Safari it shows).

    Anybody got the same problem?

  • Carsten

    Good news:
    As soon as I switched from basic building and testing in Webkit to XCode/Iphone-Sim all the remaining problems just vanished. Doubling of clicks, updating of the scroller, forms – everthing works perfectly in the simulator.
    Will post here once the app is on the actual device and how it works out.

  • claudio

    Awesome, thanks!!! Keep up the good work.

  • tdskate

    Have you found a solution for fixed video objects in a scrolling element ?
    I have the same problem…

  • Abraham


  • Abraham

    I have not found any solutions, I’ll be sure to post if I do.

  • Tdskate

    Could it be possible that video objects on iPad don’t respond to touchmove events, and are by design locked to the window viewport?

  • David Aurelio

    Hey Guys,

    sorry I haven’t been here for so long.

    The bad news: I’ve run into the video issue too. I think it is simply a problem with “replaced objects” and -webkit-transform – I don’t know any solution to the problem other than displaying videos in an overlay.

    The good news: I’ve invested much work into experimenting with animations and transitions and into code cleanups. You will see a new version shortly.


  • Tim

    David – Looking forward to testing the new version. I’ve been able to plug the current Master branch version in to my web app for the iphone platform. I’ve conditionally turned off TouchScroll for Android devices in this app. Experiencing issues with flicking locking up the scrolling and touch input for a number of seconds as well as issues with the soft keyboard not going away when I click on an element in the scroll div. Hoping the new version will fix these 2 issues. Keep up the good work.

  • tdskate

    @ anyone
    I’d really like it if onorientationchange, my TouchScroll object could reset its content to the most top left position. Is that possible?

  • Dman

    Wow this looks really polished. If I release something to app store with this, where do I need to give credit? Some sort of about page, or the support page for the app. Phonegap user.

  • tdskate

    Another small problem:
    If elements inside a TouchScroll trigger a touchmove event (added by XUI), the scrollbar will stay visible …

  • tdskate

    ignore last comment, it’s not so :)

  • Andre

    I can’t get this to run on Android (2.2). The content is not scrolling at all. Any suggestions?

  • Andre

    More info:
    It looks like the call to “new CubicBezier()” isn’t working…

  • tdskate

    Are you using the minified version of touchscroll in the dist folder? or the source file? because if you use the source folder you’ll need to add this script:

  • David Aurelio

    @Tim: I will change quite some things for Android … Also, I’m not sure if a separate scroller (based on scrollLeft/-Top) wouldn’t be a better solution.

    @tdskate Resetting the scroller is possible: Connect to the “orientationchange” event and call scrollTo(0, 0) on the scroller instance (not the DOM element)

    @Dman TouchScroll ist BSD-Licensed. You can basically do what you want with it as long as the copyright notice *in the source code* remains intact. No attribution in the UI of the app is needed.

    @Andre – I still have to do tests with Android 2.2 and as stated above, maybe a different solution will work better. I’ll let you know. Also look at tdskates latest comment.

  • John Funtymeeee

    In replky to post 60, thank you very much.

    I was begining to go crazy trying to stop the clicking twice bug when using click events within jquery. in summary this is what worked for me after reading your post.

    //do some stuff

    return false;

    The above only works on an actual iphone or ipod touch. To test your code works you can swap the mouseup with click and test on Safari using an iphone user agent, example

    //do some stuff

    return false;

    Once again thank you very much Carsten, post 60 was a blessing this week.

  • Pingback: Ajaxian » Dojo 1.5 is Out and it’s Feature Packed!

  • Pingback: Live Demo the jQTouch Driven, iPhone-Optimized Webapp Portfolio « Generation @tL

  • Rafi Ton

    Great Library!
    I’m trying to use touchscroll on an android device with phoneGap using the instructions above to scroll a div with content while keeping a tab bar fixed on the bottom of the screen, but, I cant make the div scroll.

    I’m trying to make div id #boxes with class .scroller scroll:

    Here is the code I’m using:

    var screenWidth = window.innerWidth;
    var screenHeight = window.innerHeight;
    var tabBarTop = parseInt(screenHeight – 45) + “px”;
    var boxesHeight = parseInt(screenHeight – 45) + “px”;

    if (android_version<8) { // android 2.2 works perfectly with position:fixed.
    $("#boxes").css('height', boxesHeight);
    $("#boxes").css('width', screenWidth);
    var scrollNode = document.querySelector(".scroller"), options = {};
    var scroller = new TouchScroll(scrollNode, options);

    Any ideas?


  • David


    I have the same problem with the tabbar being cropped in the simulator via phonegap but not in desktop safari. It seems about half of the height is missing.

    Did you find a cause and solution in the end?

  • Matt

    So I can’t get this to work at all. Trying to use it with JQTouch.

    I’ve surrounded a ul element with a div with class “scroller”. This div has overflow:hidden and a fixed width and height.

    I have the following in my js file:

    var scrollNode = document.querySelector(“.scroller”), options = {elastic: true};
    var scroller = new TouchScroll(scrollNode, options);

    All I’ve succeeded in doing is locking up scrolling completely. Whatever I see on the screen is now what I get, even if there are 40 more elements below the fold on the iphone.

    Anything else I should be doing?


  • Norman

    Great work David!

    works great for me with PhoneGap on the iPad

    to improve it, i would suggest following:

    1) make a downloadable archive with everything required (also css)
    first i tried it without the css and i was wondering how this shall work.. after i recognized that it didnt work, i dl the demo and extracted the css from there.. then it was fine

    2) make an option to automatically setupScroller (or was it setupConfig?)
    i have a scrollable list of ul>li with images inside the li. problem is that the height of the ul increases after the touchScroller has been attached… now i had to make onload events for all images to manually fire the setupScroller method
    i think a lot of ppl have scrollable contents with images, so maybe u could provide such a method out of the box

    regards and greetings to all uxebus

  • Dammad

    Any progress on support for android 2.2? Doesn’t work on any 2.2 device I’ve tried.

  • CW

    Hi All,

    David, great work, looking to use this in an upcoming project.

    I have created a demo using a single scroller, applying css media queries to change the location of the scroller on the page (at the bottom in portrait mode, at the right in landscape mode)

    If I change orientation when the scroller has been moved, the ‘new’ scroller does not seem to display correctly it seems as if it is being offset. When you touch the offending scroller, it seems to ‘jump’ back in to place, and works fine.

    Really hard to explain, so here is a link:

    if you view in landscape mode, scroll the right hand scroller down, and then flip to portrait, you will see what I mean.

    I have tried using scrollTo(0, 0) to no avail.

    I was wondering if anyone else had experienced such behaviour. Any help on this would be hugely appreciated.

  • Nikolai Onken

    @Dammad just when you asked a fix from @rowanbeentje came in which seems to fix 2.2


  • Pe16

    I want to use

    window.scrollTo(0,1) on my page wich uses Touchscroll so that i can hide the iphone URL bar in mobile safari.

    window.onload = function() {
    setTimeout(function(){window.scrollTo(0, 1);}, 100);

    works on all pages except the one wich uses touchscroll.

    Do you have a suggestion?

  • Greg

    Ditto to what everyone else has said, David. Absolutely wonderful work that we’re using this end to develop a HTML5 webapp protein data viewer through both your libraries and code examples, initially for iOS4.

    On a vanilla Nexus One (Android 2.2) scrolling does seem broken, but I’ll check the Bezier lead mentioned above.

    Thanks again

  • greg

    OK, should have read the posts above more closely. David’s Android 2.2 fix checked in Early September fixes everything. Very cool, have TouchScroll running on both iOS4 and Froyo.
    Thanks again

  • cgm

    Nice work.
    Is there a particular reason why the listeners are added to the document rather than the element selected for the TouchScroll. Since the default scrolling isn’t working if one element is assigned a TouchScroll.
    But if i assign them to the element only … it works both ways.


  • Jim

    How do you move a horizontal scroll left when you update the contents with new content?

  • Jim

    “Connect to the “orientationchange” event and call scrollTo(0, 0) on the scroller instance (not the DOM element)”..

    This doesn’t really answer the question.
    Can you provide sample code to call?

  • CJ

    After implementing the script, my scrolling worked fine but I noticed on the iPad it completely disabled two finger zooming not for the scrolling content but the entire page. Any workaround for this?

  • Pingback: » Blog Archive » Mobile Apps 4: forking JQTouch

  • jrotondo

    Why am I getting the error: WebKitCSSMatrix is not defined? I’m including the CSS file and minified script on my page.

  • Palma

    Hi David,
    You said “At the moment you can use “scroller.scrollTo(0, 0)” – on the scroller instance”
    I have this issue and don’t totally understand your response. where do we put this code in exactly?
    Can you show an example?

  • Daniel

    Hi David,

    I’m using touchscroll in combination with dijit/dojo.
    Everytime I initialize the TouchScroll obj the dojo content is hidden.
    Without dojo it works without any problems.
    There are no errors (debug-console of my iphone) and it’s really very annoying to develop on an iphone ;).

    Do you know a solution?

  • Tobias

    Doesn’t work on my Desire.

  • Razvan Gavril

    Is there a way to enable scrolling but keep the zoom functionality active ?

  • Keigo IMAI

    Hi, I made some analysis on CSS3 animation in Android 1.5-2.2.
    Hope this will help you:

    And if you find the answer to my question above, please answer it in the comment form!

  • Kevin

    Have you had any luck solving the problem of using forms on Android? Everything else works beautifully in my app, and forms are the only hurdle.

  • laurie ross insurance

    Richie, yea right…


  • TimG

    Has anyone else tested this on an Android tablet? It doesn’t work at all on any of the Webkit browsers on my Samsung Galaxy Tab, but is fine on my iPhone 3GS.

  • Vijay

    Hi David,

    drop down(select box) doesn’t work if you add scrolling, any idea on this??

  • vijy HR

    Hi All,
    drop down(select box) doesn’t work if scrolling is added, any idea or solution or suggestion???
    Any help would be appreciated.

  • Paul

    I’m having some issues restricting (or masking) the height of the scrolling div. Also, how do you allow the container itself to scroll. In other words, I want the whole page to scroll but the content div to scroll independently. AHH HELP!

  • Brad

    I just tried the demo on our HTC Droid Incredible running Android 2.2 and it doesn’t work at all. The about page comes up and I can see the header and footer, but the text does not scroll. If I click on the Horiz button to see the image, it doesn’t scroll either.

  • thongor

    I got the selectbox working. Try it out if it is working for you, too:


    $(‘#body’).touchScroll({selects: $(‘#body select’)});


  • Santiago Boekelman

    Merely wanna state that this is very useful , Thanks for taking your time to write this.

  • Dan

    Just wanted to say thanks for this work. Using it and it works great. If you’re open to feature requests, paging would be sweet.

    Thanks again.

  • David Aurelio

    @TimG: As soon as I find the time there will be a release that is compatible with newer Android devices.

    @Vijay: That’s a limitation caused by the implementation. For compatibility with Android < 2.2 the “touchstart” event has to be preventDefault’ed. That means, that the native click event does not occur and a synthesized click needs to be fired. Select boxes need a native event to open up. I didn’t manage to find a way to open selects programmatically.

    @Paul The “master” branch has global scrolling disabled … I’ll see if there is a good way to make it optional in the next release.

    @Brad: You may want to check out one of the “experimental” and “scroll-left-top” branches from github.

    @Santiago/@Dan I’m glad you like it :-) Nice words are motivating.

    @Dan there is a paging feature … the initialization option is {snapToGrid: true}

  • William Panting

    I’ve been working on this project:
    It is a framework that creates a native like master/detail UI for mobile webkit browsers. I hope you might find something helpful or interesting in it.

  • Jefferson

    I tried to use your solution with an iframe inside a div, but it doesn’t work.
    My test was based on the demo and i put the content of the div “about” inside another html file, like this:

    I also tested without the class definition in the iframe.
    Someone tried this?

    Thanks for your effort!

  • Jefferson
  • Jefferson

    Sorry, i forgot to change the code:

    <div class=”scroller” id=”about”>
    <iframe class=”scroller” id=”ifrmIdentify” src=”contentiframe.html”></iframe>

  • Bernie Habermeier

    Super awesome work! Congrats on this. It actually performs well on some lower-end android phones, which is just marvelous!

    Some quick notes:

    a. I’d like to see some method(s) added that can provide JS code with pixel-offset information. I think something like this kind-of-works:

    function getScrollerOffset(obj) {
    var matrix = obj._currentOffset.translate(0,0,0);
    return { x: matrix.e, y: matrix.f };

    where obj is the TouchScroll object in question. I do see some issues when the scroll hits the borders — it’s not right at that point.

    Might be nice to set up some call-backs that would fire if certain pix-distance got scrolled with a flick (or on end of a flick). Would come in handy for scrolling a simulated large surface where you want to move tiles into place.

    b. You probably knows this, but dist/touchscroll.min.js is different from src/touchscoll.js. Making it a wee bit hard to see what’s happening in the code that I’m running with. Unfortunately the current dist version performs much faster on some slower Android phones (example Android 2.2.2 — Droid), so I kind of want to stay with the dist version.

    c. Currently there are JavaScript errors just when you include this library on desktop browsers (FireFox, for example). I’m not even talking about creating or running it, but just including the JavaScript file causes this issue. Might be nice for the code not to cause errors, even if it’s running in environments that are not targeted. By the way, currently Chrome can deal with the dist version Okay, but Safari generates a lot of the following errors: Result of expression ‘this._trackedEvents[1]‘ [undefined] is not an object. Not a high priority, but just might be nice to clean that up.

    Your library rocks, keep up the great work!

  • Bernie Habermeier

    Oh — I now see a function that updates the offset info that I need to get: _determineOffset(). So when I call this before grabbing the _currentOffset, looks like works.

  • http://inproduction.. sokr8

    Hy there David, i use your framework for an iphone webapp of mine, i have one problem with Touchscroll and that is: I can’t hide the URL/Toolbar.

    Something like this hides the URL on safari mobile:
    window.onload = function() { setTimeout(function(){window.scrollTo(0, 1);}, 100); }

    That works on everypage exept touchscroll enabled page. I think i saw somewhere you admitted this as a feature to be made.

    Is there any progress made or do you know of a workaround?

    Thx in advance

  • http://inproduction.. sokr8
  • Pingback: Mobile Application Development: Web vs. Native | Software Downloads And Answers

  • Pingback: iPhone – Scroll conteúdo com tamanho fixo (width/height) - Omugo

  • jax

    The demo doesn’t work on my Android 2.2.1 device… known issue?

  • Chef

    Can I disable touchscroll for some time and then turn it on again? Thanks

  • Mike


    Thank you for the script.

    Unfortunately I get the following 2errors in firebug:
    touchscroll WebKitCSSMatrix is not defined
    TouchScroll is not a constructor

    I have linked the css, and js:

    Am I missing something?


  • Elia

    I having some issues limiting (or masking) the height of the scrolling div. Also, how do you enable the pot itself to scroll. Pretty simply, I want the complete page to scroll but the content div to scroll independently.

  • itsid

    I’m Sorry, maybe I’m just plain stupid …
    i just stumbled across this nice script, and because I stopped trying to use iScroll which messes my site (nevermind, not their fault!) I’d love to give this approach a try.

    Now for the problem I’m having, right at the start.
    I need to have a yet unknown number of scrolls in my resulting page,

    The layout itself looks like this:


    Some Description That is long enogh to require scrollability

    So within every flip-box there is an image a title and a description
    The title is hidden, so is the description as long as the image doesn’t get a click-event.
    Afterwards it just flips around with those fancy webkit rotateY(180deg) possibilities we have these days ;)

    The Problem now is, how do I setup the scrollers not only to find my descriptions but to set them up in a way I can call them like you do in your demo ( scrollers[item].setupScroller(true) ) since on startup, all my scrollers Object does have is a __proto__ and none of my descriptions are found. I hoped I could add the parents id (since that is the only Id I have here) but i just don’t know how ;)

    And, because I’m sure I will need to know afterwards:
    On hiding the element again, how do I unset the scroller again
    since the description will flip 180deg back to the image sooner or later ;)

    Thanks a million for your kind help


  • itsid

    Uuups, no special-chars in here… again the layout pre-special-char’d ;)
    <div class="item">
    <div class="flip-box" id="item_1">
    <div class="media flip">
    <img src="files/s_17206.jpg" />
    <h1 class="nfo">SOME TITLE</h1>
    <div class="descript flip">
    <h3>Some Description</h3> <p>That is long enogh to require scrollability</p>

    (I hope it’s now readable)

  • itsid

    okay, plain stupid it is then ;)

    updated to 0.2 alpha 3 and except that it’s flipping the container on touchend back to the image again it’s working like a charm.
    So thanks a million, this one helped A LOT (increased fontsize, bold, underlined ;))


  • xceed

    Has anyone got this working on Android 2.2 ?

    Scrolling doesn’t seem to work at all even in basic configuration with no fixed elements?

  • Jeffrey Bennett

    Fantastic work! This is exactly what I’ve been looking for. Thank you for posting this.

  • Abe Sanchez

    Anyone know why it disables the zoom function on iPhone and iPad? It works fine on my HP Touchpad and Pre….. Thanks in advance.

  • Junaid

    Hey, I want to scroll element on top of screem … like scroller.scrollToElement(el);
    is it possible?

  • Alex

    How to destroy ScrollTouch object to free memory?

  • Prem

    Sir ,
    How to change the touch scrollbar for horizontal
    by using config variable

  • Pingback: Dojo 1.5: Ready to power your web app | Blog | SitePen