The onmousewheel event of JavaScript

Home

With the ubiquity of the mouse wheel for navigating web pages comes a JavaScript event for developers to take advantage of that- the "onmousewheel" event. As its name suggests, this event fires whenever the user rotate the mouse wheel either upwards or downwards, most commonly to scroll a webpage. You probably won't be accessing this event all that frequently, unlike say "onmouseover", but for that certain JavaScript application where it's natural to reach for the wheel and give it a good spin, this event makes it happen. A high profile example of "onmousewheel" in action would be Google Maps, which zooms in and out of a map whenever the user turns the mouse wheel. Your plans for "onmousewheel" I'm guessing will be a tad less audacious than that.

`onmousewheel` event and Firefox's equivalent

First thing's first- compatibility. "onmousewheel" is supported in IE6, Opera9+, Safari2+, and Firefox1+, though in FF (as of FF3.x), the equivalent "DOMMouseScroll" should be used, as "onmousewheel" as an event name isn't yet recognized. With that said, the below illustrates binding the "onmousewheel" event to the document object of the page:

var mousewheelevt=(/Firefox/i.test(navigator.userAgent))? "DOMMouseScroll" : "mousewheel" //FF doesn't recognize mousewheel as of FF3.x

if (document.attachEvent) //if IE (and Opera depending on user setting)
	document.attachEvent("on"+mousewheelevt, function(e){alert('Mouse wheel movement detected!')})
else if (document.addEventListener) //WC3 browsers
	document.addEventListener(mousewheelevt, function(e){alert('Mouse wheel movement detected!')}, false)

The above does nothing more than alert a message whenever the mouse wheel is rolled inside the page, though illustrates the basic setup nicely. We test for Firefox and use the event name "DOMMouseScroll" instead of "mousewheel" before going about binding the event to the target object, in this case, the document. Note that "DOMMouseScroll" can only be binded dynamically using addEventListener(), unlike regular events that can also be directly attached to the target object.

Ok, with the basic construct out of the way, lets get to the nitty gritty details of how "onmousewheel" works now. When this event fires, the event property "wheelDelta" in non FF browsers, and "detail" in FF, is populated with an integer that indicates whether the wheel moved up or down, and by how many "clicks". In the case of "wheelDelta", it returns a an integer that's always a multiple of 120, whereby a value of 120 means the mouse wheel has been moved up one "click", while -120 means down one "click". If the user quickly moves the mouse wheel 3 clicks upwards for example, "wheelDelta" returns 720. For "detail" (applicable only in FF), the number returned in a multiple of 1 instead, where 1 means the mouse wheel has been moved down one "click", while -1 means up one "click". This is the reverse of what "wheelDelta" returns as far as signage.

Lets attempt to untangle what gets returned when the mouse wheel is moved and in which browsers with the following chart:

Event property	Applies to event:	Up 1 click	Up 2 clicks	Down 1 click	Down 2 clicks
e.wheelDelta Supported in Non FF browsers	`onmousewheel` and in non FF browsers	120	240	-120	-240
e.detail Supported in FF and Opera	`DOMMouseScroll` and in FF (as of FF3.x)	-1	-2	1	2

An important browser note- while Opera reacts only to the "onmousewheel" event, it populates both the event properties "wheelDelta" and "detail" when that occurs. In Opera, "detail" returns the same value as it does in FF, so for the big O you should rely on "detail" instead of "wheelDelta", which depending on the Opera version may return a different value than in IE's.

I don't know about you, but the first thing I want to do is equalize the integer that gets returned by the mouse wheel event, so just one pair of numbers is returned across browsers. Lets go with the +-120 scheme for up and down one mouse wheel click, respectively:

Wheel Delta value:

<h2>Wheel Delta value: <span id="wheelvalue"></span></h2>

<script type="text/javascript">

function displaywheel(e){
	var evt=window.event || e //equalize event object
	var delta=evt.detail? evt.detail*(-120) : evt.wheelDelta //check for detail first so Opera uses that instead of wheelDelta
	document.getElementById("wheelvalue").innerHTML=delta //delta returns +120 when wheel is scrolled up, -120 when down
}

var mousewheelevt=(/Firefox/i.test(navigator.userAgent))? "DOMMouseScroll" : "mousewheel" //FF doesn't recognize mousewheel as of FF3.x

if (document.attachEvent) //if IE (and Opera depending on user setting)
	document.attachEvent("on"+mousewheelevt, displaywheel)
else if (document.addEventListener) //WC3 browsers
	document.addEventListener(mousewheelevt, displaywheel, false)

</script>

Scroll your mouse wheel up and down, and see the value that the variable "delta" returns, which is now consistent across browsers as far as signage.

Changing an image using the mouse wheel

Lets put the "onmousewheel" event to some simple but practical use now. How about an image that can be changed by moving the mouse wheel up or down over it?

Demo (scroll mouse wheel up or down when cursor is over image):

Here's the code:

<img id="slideshow" src="summer.jpg" />

<script type="text/javascript">

var myimages=[
	"summer.jpg",
	"spring.jpg",
	"winter.jpg"
]

var slideshow=document.getElementById("slideshow")
var nextslideindex=0

function rotateimage(e){
	var evt=window.event || e //equalize event object
	var delta=evt.detail? evt.detail*(-120) : evt.wheelDelta //delta returns +120 when wheel is scrolled up, -120 when scrolled down
	nextslideindex=(delta<=-120)? nextslideindex+1 : nextslideindex-1 //move image index forward or back, depending on whether wheel is scrolled down or up
	nextslideindex=(nextslideindex<0)? myimages.length-1 : (nextslideindex>myimages.length-1)? 0 : nextslideindex //wrap image index around when it goes beyond lower and upper boundaries
	slideshow.src=myimages[nextslideindex]
	if (evt.preventDefault) //disable default wheel action of scrolling page
		evt.preventDefault()
	else
		return false

}

var mousewheelevt=(/Firefox/i.test(navigator.userAgent))? "DOMMouseScroll" : "mousewheel" //FF doesn't recognize mousewheel as of FF3.x

if (slideshow.attachEvent) //if IE (and Opera depending on user setting)
	slideshow.attachEvent("on"+mousewheelevt, rotateimage)
else if (slideshow.addEventListener) //WC3 browsers
	slideshow.addEventListener(mousewheelevt, rotateimage, false)


</script>

Note the use of preventDefault() and return false to disable the default mouse wheel action when the cursor is over the image, which is to scroll the page.