Getting rid of the “Gray Box” in PhoneGap for Windows Phone

If you’ve ever used a Windows Phone device’s web browser, then you have probably noticed the gray highlight that the Windows Phone browser puts on top of the HTML content any time that you click on a link. For static web pages, this isn’t a big deal. It indicates that you have clicked on an item. However, if you are building apps with dynamic content, this can become much more frustrating and can have a negative impact in overall user experience.  Fret not, TouchClick.js is here to help!

In PhoneGap applications, you can build experiences that respond to mouse/touch events, which can be more dynamic than what is supported in the device browser. Note: The device browser does not support mouse events. All touch input gets translated into mousedown, mousemove, or mouseup events inside of the PhoneGap container. This gray highlight can become a major pain point in highly-dynamic applications. Luckily, I’ve found a way to get rid of it. Check out the video below to see an example of the gray highlight, as well as the workaround in action:

Through lots of trial and error, I’ve found that the gray highlight is applied to all <a> anchor elements, and any html element that has a “click” event handler or lingering “mousedown” and “mouseup” event handlers.   Luckily, you can manage event listeners and add/remove event handlers as necessary so that you minimize the gray box.  This approach does not get rid of the gray box 100% of the time, but I think it’s safe to say that it gets rid of it 90% of the time.  After applying these techniques, I only see the gray highlight if you tap on multiple clickable items in rapid succession.

Here’s how I was able to get rid of the gray highlight box:

  1. Do not use <a> anchor tags ever.
  2. Assign a “mousedown” event handler to the <span>, <div> or other element that you want to be clickable.
  3. When the “mousedown” event handler is invoked, remove the “mousedown” event handler, save the mousedown input coordinates, and add a “mouseup” event handler to the window object.
  4. When the “mouseup” event handler is invoked, remove the “mouseup” event handler, and then compare the mouse coordinates. If the mouse coordinates have not changed, and its within a reasonable amount of time, you can infer that this should be a “click” event, and invoke an action as desired.
  5. Set a timeout to restore the “mousedown” event handler in an asynchronus operation.   If you re-add the “mousedown” event handler inside of the “mouseup” event handler, you will still get the gray box.

To make things even more confusing, if you have dynamic content (changing DOM elements) underneath of your touch input, then you get multiple mousedown and mouseup events invoked on different DOM elements underneath where you touched.  This happens even if you only touched the screen once. I was able to intercept mouse events and prevent their default actions to mitigate this behavior.

Sounds confusing, right?  Well, it can certainly be tricky.  Luckily for us all, I was able to encapsulate all of this functionality inside of a reusable JavaScript class that anyone can use without needing to understand all of the ins & outs.   The TouchClick.js class is available in the example on github under “WinPhone-NoGrayBox“.  In the TouchClick.js library, it override the default HTMLElement’s addEventListener function and intercepts all calls to addEventListener( “click”… ) and replaces it with the TouchClick behavior, which will perform a click action, but without the gray highlight box.  Thus making your app experience better, and keeping your code simple.

Once you include TouchClick.js, you add event listeners as you normally would, and it even works with jQuery’s event wrappers:

myElement.addEventListener( "click", clickHandler1 );
$("#myElement2").on( "click", clickHandler2 );
$("#myElement3").click( clickHandler3 );

Download TouchClick.js today from today, and start building more great experience for Windows Phone using PhoneGap.

Thanks to @purplecabbage for pointing me in the right direction with mouse events inside of PhoneGap on Windows Phone!

More detail will be available on the app shown in the video at a later date – That app was created using app-UI for rich mobile experiences.

  • Yuriy

    that’s a good news!
    in the video i noticed a tab with map (looks like leaflet library?) did you managed to make functional scroll/pan? (probably not, but who knows…)

    • Andrew

      Yurly, Yes, this is using leaflet. I made a few minor modifications that enable it to work on Windows Phone, which I’m planning to submit back to the open source project. It still gets a few gray box higlights every now and then depending on what you are doing, and pinch gestures are not supported, but it is very functional.

  • Brian Rinaldi

    Does this mean you have to do an entirely separate UI layer for Windows Phone or does the library do some sort of device detection?

    • Andrew

      Currently, I have a forked branch of app-UI for windows phone, but im going to be integrating this back into app-UI over the next week or so… I hope to have device detection built in, and have it set itself up accordingly, but I don’t have it fully implemented yet.

  • Marco

    Thank you!!!

  • Magnus

    I’m trying to get this to work with Leaflet, but I’m having no luck with it.

    Is there another version of TouchClick that I should use?

    • Andrew

      I had to actually modify the Leaflet source to get this working. TouchClick by itself won’t do it… let me try to track down what I changed.

  • Magnus

    Thank you, that would be much appreciated.

  • Niklas Enskog

    I’m also interested in getting Phonegap for Windows Phone to work with Leaflet. I’m curious to find out how you got Leaflet to behave so nice. Did you create external overrides or change the actual source files?

    Any way you could publish the project as a whole for reverse engineering purposes?

  • Derek

    You can also try with * { -ms-user-select: none; }

  • Tim Bourguignon

    For people landing on this article more than a year later, there is now finally a simple solution that works for WP8: adding in the header of your files (source:

    • ViniKatyal

      Thanks so much 🙂