Status Tap/Scroll To Top in PhoneGap Apps on iOS

One criticism of PhoneGap apps that I sometimes hear is that they often don’t have “standard” features from the native operating system.  Little things, like iOS’s ability to scroll a container back to the top, just by tapping on the operating system’s status bar. These types of features are not hard to add to a PhoneGap application, at all. This is more of an “attention to detail” issue, not something that the platform can’t do.

Since this isn’t a feature that is applicable on all platforms, and it can vary per PhoneGap app implementation, it is not part of the core PhoneGap/Cordova download.  However, this can be very easily added via a native plugin.  Native plugins enable you to access native code, or augment the capabilities of PhoneGap for a particular platform.

Here’s proof… I just added the “scroll to top” capability to my Halloween PhoneGap app.

If you download the app from the app store today, you won’t see this yet because I literally *just* submitted it to Apple.

So how did I do this?

It wasn’t hard. The first thing to do is check and see if there was an existing native plugin that has already been created by someone in the PhoneGap/Cordova community.  It turns out, Greg pointed out one that already existed.  Since this plugin was built targeting an older version of PhoneGap, and my project was built using PhoneGap 3.0, I had a few minor updates.  Though, I was able to get everything all set up in a very short period of time.

Here’s what I did:

  1. I forked the existing plugin.
  2. Added plugin.xml metadata so the plugin can be included via PhoneGap & Cordova CLI tools.
  3. Added logic in the JavaScript so that it auto-initializes – you no longer have to manually initialize the plugin.
  4. Moved the native Objective-C initialization logic into a background thread.

Now that I’ve done this, and pushed it to github, you can include it into your own PhoneGap projects with a single command using the PhoneGap CLI:

phonegap local plugin add

Then, in your PhoneGap application, you just have to add an event listener for the “statusTap” event, which is triggered when the user taps on the operating system’s status bar.  It is literally this simple:

window.addEventListener("statusTap", function() {
  alert("status tap");

This just shows an alert that the status bar was tapped. If you want to animate specific containers, you have to do this manually yourself via JavaScript. Again, that isn’t hard to do. Here’s an excerpt that I used from the Halloween app, using jQuery syntax:

window.addEventListener("statusTap", function() {
    var target = $("#scroller");

    //disable touch scroll to kill existing inertial movement
        '-webkit-overflow-scrolling' : 'auto',
        'overflow-y' : 'hidden'

    target.animate({ scrollTop: 0}, 300, "swing", function(){

        //re-enable touch scrolling
            '-webkit-overflow-scrolling' : 'touch',
            'overflow-y' : 'scroll'

This disables touch scrolling to kill any inertial scrolling in progress, animates the scroll to top, then re-enables touch scrolling once the animation is complete.

That’s it…  Go check out the code, fork it, or use it in your own project:


  • Justin McNally

    Happy to accept a PR.

    • Andrew Trice

      Would be happy to. Looks like you already beat me to integrating the changes. Great stuff!

      • Justin McNally

        Hope u dont mind, your changes looked awsome so i wanted to get them in asap. If you dont like thr way i credited you feel free to send a revised Readme

        • Andrew Trice

          Thanks! Nah, I don’t mind at all. Looks good to me. I was meaning to do a pull request, but spaced on it.

  • Dan Kantor

    Thank you!! Been wanting this for a long time. Here’s some feedback:

    When I tried to install from Justin I got an error –

    $ phonegap local plugin add

    [phonegap] adding the plugin:


    throw err;


    Error: Unencoded <

    Line: 1

    Column: 2

    Char: <

    at error (/usr/local/Cellar/node/0.10.6/lib/node_modules/phonegap/node_modules/cordova/node_modules/elementtree/node_modules/sax/lib/sax.js:347:8)

    at strictFail (/usr/local/Cellar/node/0.10.6/lib/node_modules/phonegap/node_modules/cordova/node_modules/elementtree/node_modules/sax/lib/sax.js:364:22)

    at Object.write (/usr/local/Cellar/node/0.10.6/lib/node_modules/phonegap/node_modules/cordova/node_modules/elementtree/node_modules/sax/lib/sax.js:671:11)

    at XMLParser.feed (/usr/local/Cellar/node/0.10.6/lib/node_modules/phonegap/node_modules/cordova/node_modules/elementtree/lib/parsers/sax.js:48:15)

    at ElementTree.parse (/usr/local/Cellar/node/0.10.6/lib/node_modules/phonegap/node_modules/cordova/node_modules/elementtree/lib/elementtree.js:263:10)

    at Object.exports.XML (/usr/local/Cellar/node/0.10.6/lib/node_modules/phonegap/node_modules/cordova/node_modules/elementtree/lib/elementtree.js:593:13)

    at Object.module.exports.parseElementtreeSync (/usr/local/Cellar/node/0.10.6/lib/node_modules/phonegap/node_modules/cordova/node_modules/plugman/src/util/xml-helpers.js:120:38)

    at /usr/local/Cellar/node/0.10.6/lib/node_modules/phonegap/node_modules/cordova/node_modules/plugman/src/util/plugins.js:67:39

    at /usr/local/Cellar/node/0.10.6/lib/node_modules/phonegap/node_modules/cordova/node_modules/shelljs/shell.js:1707:7

    at ChildProcess.exithandler (child_process.js:635:7)

    I was able to install from Andrew. It works like a charm. The only thing I had an issue with was removing and adding -webkit-overflow-scrolling. It caused some weirdness for me. I've tried using that technique before and also had issues. It's not a huge deal though since it still scrolls up without doing that. Thanks!

  • gurunathan natarajan

    IT’s Simple Super …. I want To Add This To My project For Windows Phone7 application If it Possible ….. If phonegap 2.9.0 Support This Function ….And I need The Status Bar On Bottom How?

  • Pete

    Sounds like just what I need. Is this supposed to work in conjunction with the native navigation bar?

    I can’t seem to get it to fire.

  • Scott Veltkamp

    Hello, I just tried the plugin and it seems to work ok, except that after a few second of using the app, the status bar completely disappears. I’m using the latest phonegap, and IOS 7

    • András Klikk

      I have the same problem, probably the plugin is bugged for iOS7. Would be very nice if you would have the time to update it. Thanks in advance. Let me know If I can help in any way.