Mouse wheel programming in JavaScript	2.5/5.0 (6 votes total) Rate: Select 1 - Terrible 2 - Poor 3 - Average 4 - Good 5 - Outstanding
Adomas Paltanavičius July 25, 2006

Web applications are becoming more and more like “normal” desktop applications. Of course, they are more and more functional, but smooth user interface acts the primary role. So we have drag and drop, autocompletition, and much more. Many of those nice features got possible only with help of AJAX.

This page, however, is not about AJAX (or any other buzzword). It is about rather simple user input method -- mouse wheel. I believe it would now be difficult to find a mouse without wheel. Vast majority of users are used to the wheel as a control for scrolling in lists, zooming etc. Rather few web applications, however, make smart use of mouse wheel. This page is to provide you with general information about handling mouse wheel-generated events in JavaScript programming language.

Annotated code

Below is annotated javascript code, which should explain the magic behind mouse wheel generated events. 

/** This is high-level function.

 * It must react to delta being more/less than zero.

 */

function handle(delta) {

        if (delta < 0)

        …;

        else

        …;

}



/** Event handler for mouse wheel event.

 */

function wheel(event){

        var delta = 0;

        if (!event) /* For IE. */

                event = window.event;

        if (event.wheelDelta) { /* IE/Opera. */

                delta = event.wheelDelta/120;

                /** In Opera 9, delta differs in sign as compared to IE.

                 */

                if (window.opera)

                        delta = -delta;

        } else if (event.detail) { /** Mozilla case. */

                /** In Mozilla, sign of delta is different than in IE.

                 * Also, delta is multiple of 3.

                 */

                delta = -event.detail/3;

        }

        /** If delta is nonzero, handle it.

         * Basically, delta is now positive if wheel was scrolled up,

         * and negative, if wheel was scrolled down.

         */

        if (delta)

                handle(delta);

}



/** Initialization code. 

 * If you use your own event management code, change it as required.

 */

if (window.addEventListener)

        /** DOMMouseScroll is for mozilla. */

        window.addEventListener('DOMMouseScroll', wheel, false);

/** IE/Opera. */

window.onmousewheel = document.onmousewheel = wheel; 

Handler function

In the code above, there is “handle” function which is, of course, meant to be written by you. As you have noticed, it takes on parameter, delta. It is called so, because mouse wheel has no absolute system, and we only capture scrolling deltas, that is wheel angle changes.

Practically, you only have to watch for positive and negative values of delta. These cases are pictured on the left.

If delta is positive, wheel was scrolled up. Otherwise, it was scrolled down.

Note that in applications, scrolling up usually means page is scrolled down etc.

You might wonder, what will the actual values of delta be. In fact, the code above is adjusted in such a way that you should get -1 or +1 in 99% of all cases. Though, for instance, I have seen ±3 in Firefox if you scroll very fast. Someone in Digg reported delta of 14, and Geoffrey Kruse was able to get 76 on his Powerbook trackpad. :-) Of course, that depends on sensivity that you've set for your mouse. There is also subtlety in Firefox (at least): if you start scrolling the wheel fast and then push the right mouse button for the menu, large value of delta is reported, e.g. 30.

Robert Gerlach writes about his experience on MacOS X: “For a single turn its +-0.1, if you roll it faster, the values become bigger. This is because of Mac OS' mouse/wheel-acceleration. You move/turn it one time, it moves/scrolls 1 pixel. Then you move/turn it three times fast and it moves/turns 30 pixel”

You are also welcome to see test page.

Compatibility

I have written first version of this code in January 2006. Back then, Firefox and Internet Explorer 6 were only supported browsers. Older Internet Explorer version do not work. Thanks to Kane Barton for reporting that this works since Firefox 1.0.7 (so possibly since 1.0).

I would like to thank Jean-Luc for contributing notes on how to make the code work properly in Opera 9. That version of Opera is relatively new (as of July 2006); previous versions of Opera do not support mouse wheel.

Also thanks to Andrew Shearer, Dorian and Geoffrey Kruse for pointing out that the code works in Safari. Andrew mentions version 2.0.4, but I am not sure about earlier versions. Since Safari and Konqueror have common bits in code base, Konqueror might work too. I haven't checked yet though.

It is useful to note, however, that Opera, Safari and Firefox include automated upgrade systems that prompt users to upgrade to newer versions of the browser once it gets released.

Mouse wheel currently works on: (with earliest version known to work)

• Internet Explorer 6
• Firefox 1.0
• Opera 9. (But see this bug report.)
• Safari. (?)

Usability

(Few “don't”s.)

• Don't make wheel act unexpectedly. Users know that wheel scrolls the list of files. If there is list of files in your web application, use it. Some map programs use wheel for zooming (and so does Google Maps). So use it.
• Don't force users to depend on having wheel working. Just as it is bad practice to rely on JavaScript.

Notes

It's best when your design consists of “position: absolute” layers. If the page doesn't fit into screen, be prepared for troubles.

There is a bug in early versions of Opera 9 that might be of great concern. Hope that gets fixed soon.