wheel

The wheel event is fired when a wheel button of a pointing device (usually a mouse) is rotated. This event replaces the non-standard deprecated mousewheel event.

General info

Interface

WheelEvent

Synchronicity

asynchronous

Bubbles

Yes

Cancelable

Yes

Target

defaultView, Document, Element

Default Action

Scroll, moving history, or zooming in/out.

Properties

This event implements the properties of WheelEvent, MouseEvent, UIEvent and Event.

Properties of WheelEvent

This interface inherits properties from its parents, MouseEvent, UIEvent and Event.

WheelEvent.deltaX Read only

Returns a double representing the horizontal scroll amount.

WheelEvent.deltaY Read only

Returns a double representing the vertical scroll amount.

WheelEvent.deltaZ Read only

Returns a double representing the scroll amount for the z-axis.

WheelEvent.deltaMode Read only

Returns an unsigned long representing the unit of the delta values scroll amount. Permitted values are:

Constant	Value	Description
DOM_DELTA_PIXEL	0x00	The delta values are specified in pixels.
DOM_DELTA_LINE	0x01	The delta values are specified in lines.
DOM_DELTA_PAGE	0x02	The delta values are specified in pages.

Properties of MouseEvent

This interface also inherits properties of its parents, UIEvent and Event.

MouseEvent.altKey Read only

Returns true if the alt key was down when the mouse event was fired.

MouseEvent.button Read only

The button number that was pressed when the mouse event was fired. 

MouseEvent.buttons Read only

The buttons being pressed when the mouse event was fired

MouseEvent.clientX Read only

The X coordinate of the mouse pointer in local (DOM content) coordinates.

MouseEvent.clientY Read only

The Y coordinate of the mouse pointer in local (DOM content) coordinates.

MouseEvent.ctrlKey Read only

Returns true if the control key was down when the mouse event was fired.

MouseEvent.metaKey Read only

Returns true if the meta key was down when the mouse event was fired.

MouseEvent.movementX Read only

The X coordinate of the mouse pointer relative to the position of the last mousemove event.

MouseEvent.movementY Read only

The Y coordinate of the mouse pointer relative to the position of the last mousemove event.

MouseEvent.offsetX Read only

The X coordinate of the mouse pointer relative to the position of the padding edge of the target node.

MouseEvent.offsetY Read only

The Y coordinate of the mouse pointer relative to the position of the padding edge of the target node.

MouseEvent.pageX Read only

The X coordinate of the mouse pointer relative to the whole document.

MouseEvent.pageY Read only

The Y coordinate of the mouse pointer relative to the whole document.

MouseEvent.region Read only

Returns the id of the hit region affected by the event. If no hit region is affected, null is returned.

MouseEvent.relatedTarget Read only

The secondary target for the event, if there is one.

MouseEvent.screenX Read only

The X coordinate of the mouse pointer in global (screen) coordinates.

MouseEvent.screenY Read only

The Y coordinate of the mouse pointer in global (screen) coordinates.

MouseEvent.shiftKey Read only

Returns true if the shift key was down when the mouse event was fired.

MouseEvent.which Read only

The button being pressed when the mouse event was fired.

MouseEvent.mozPressure Read only

The amount of pressure applied to a touch or tablet device when generating the event; this value ranges between 0.0 (minimum pressure) and 1.0 (maximum pressure).

MouseEvent.mozInputSource Read only

The type of device that generated the event (one of the MOZ_SOURCE_* constants listed below). This lets you, for example, determine whether a mouse event was generated by an actual mouse or by a touch event (which might affect the degree of accuracy with which you interpret the coordinates associated with the event).

MouseEvent.webkitForce Read only

The amount of pressure applied when clicking

MouseEvent.x Read only

Alias for MouseEvent.clientX.

MouseEvent.y Read only

Alias for MouseEvent.clientY

Properties of UIEvent

This interface also inherits properties of its parent, Event.

UIEvent.cancelBubble  

Is a Boolean indicating whether the bubbling of the event has been canceled or not.

UIEvent.detailRead only

Returns a long with details about the event, depending on the event type.

UIEvent.isChar Read only

Returns a Boolean indicating whether the event produced a key character or not.

UIEvent.layerX Read only

Returns the horizontal coordinate of the event relative to the current layer.

UIEvent.layerY Read only

Returns the vertical coordinate of the event relative to the current layer.

UIEvent.pageX Read only

Returns the horizontal coordinate of the event relative to the whole document.

UIEvent.pageY Read only

Returns the vertical coordinate of the event relative to the whole document.

UIEvent.sourceCapabilities  Read only

Returns an instance of the InputDeviceCapabilities interface which provides information about the physical device responsible for generating a touch event.

UIEvent.viewRead only

Returns a WindowProxy that contains the view that generated the event.

UIEvent.which Read only  

Returns the numeric keyCode of the key pressed, or the character code (charCode) for an alphanumeric key pressed.

Properties of Event

Event.bubbles Read only

A Boolean indicating whether the event bubbles up through the DOM or not.

Event.cancelBubble

A historical alias to Event.stopPropagation(). Setting its value to true before returning from an event handler prevents propagation of the event.

Event.cancelable Read only

A Boolean indicating whether the event is cancelable.

Event.composed Read only

A Boolean value indicating whether or not the event can bubble across the boundary between the shadow DOM and the regular DOM.

Event.currentTarget Read only

A reference to the currently registered target for the event. This is the object to which the event is currently slated to be sent to; it's possible this has been changed along the way through retargeting.

Event.deepPath 

An Array of DOM Nodes through which the event has bubbled.

Event.defaultPrevented Read only

Indicates whether or not event.preventDefault() has been called on the event.

Event.eventPhase Read only

Indicates which phase of the event flow is being processed.

Event.explicitOriginalTarget Read only

The explicit original target of the event (Mozilla-specific).

Event.originalTarget Read only

The original target of the event, before any retargetings (Mozilla-specific).

Event.returnValue

A non-standard alternative (from old versions of Microsoft Internet Explorer) to Event.preventDefault() and Event.defaultPrevented.

Event.scoped Read only

A Boolean indicating whether the given event will bubble across through the shadow root into the standard DOM. This property has been renamed to composed.

Event.srcElement

A non-standard alias (from old versions of Microsoft Internet Explorer) for Event.target.

Event.target Read only

A reference to the target to which the event was originally dispatched.

Event.timeStamp Read only

The time at which the event was created, in milliseconds. By specification, this value is time since epoch, but in reality browsers' definitions vary; in addition, work is underway to change this to be a DOMHighResTimeStamp instead.

Event.type Read only

The name of the event (case-insensitive).

Event.isTrusted Read only

Indicates whether or not the event was initiated by the browser (after a user click for instance) or by a script (using an event creation method, like event.initEvent)

Methods

This event implements the methods of WheelEvent, MouseEvent, UIEvent and Event.

Methods of WheelEvent

This interface doesn't define any methods, but inherits methods from its parents, MouseEvent, UIEvent and Event.

Methods of MouseEvent

This interface also inherits methods of its parents, UIEvent and Event.

MouseEvent.getModifierState()

Returns the current state of the specified modifier key. See the KeyboardEvent.getModifierState() for details.

MouseEvent.initMouseEvent()

Initializes the value of a MouseEvent created. If the event has already being dispatched, this method does nothing.

Methods of UIEvent

This interface also inherits methods of its parent, Event.

UIEvent.initUIEvent()

Initializes a UIEvent object. If the event has already being dispatched, this method does nothing.

Methods of Event

Event.initEvent()

Initializes the value of an Event created. If the event has already being dispatched, this method does nothing.

Event.preventBubble() Obsolete since Gecko 24

Prevents the event from bubbling. Obsolete, use event.stopPropagation instead.

Event.preventCapture() Obsolete since Gecko 24

Obsolete, use event.stopPropagation instead.

Event.preventDefault()

Cancels the event (if it is cancelable).

Event.stopImmediatePropagation()

For this particular event, no other listener will be called. Neither those attached on the same element, nor those attached on elements which will be traversed later (in capture phase, for instance)

Event.stopPropagation()

Stops the propagation of events further along in the DOM.

Event.getPreventDefault()

Non-standard. Returns the value of Event.defaultPrevented. Use Event.defaultPrevented instead.

Specifications

Browser compatibility

[1] Internet Explorer exposes the wheel event only via addEventListener, there is no onwheel attribute on DOM objects. Bug report.

[2] This mapping was implemented to allow developers to implement simple zooming functionality using the pinch-to-zoom gesture on mobile screens/trackpads (mousewheel + Ctrl commonly zooms).

Listening to this event across browser

The following script creates a global addWheelListener method that allows to listen to the different wheel events across browsers and prevent the default behavior.

// creates a global "addWheelListener" method
// example: addWheelListener( elem, function( e ) { console.log( e.deltaY ); e.preventDefault(); } );
(function(window,document) {
    var prefix = "", _addEventListener, support;
    // detect event model
    if ( window.addEventListener ) {
        _addEventListener = "addEventListener";
    } else {
        _addEventListener = "attachEvent";
        prefix = "on";
    }
    // detect available wheel event
    support = "onwheel" in document.createElement("div") ? "wheel" : // Modern browsers support "wheel"
              document.onmousewheel !== undefined ? "mousewheel" : // Webkit and IE support at least "mousewheel"
              "DOMMouseScroll"; // let's assume that remaining browsers are older Firefox
    window.addWheelListener = function( elem, callback, useCapture ) {
        _addWheelListener( elem, support, callback, useCapture );
        // handle MozMousePixelScroll in older Firefox
        if( support == "DOMMouseScroll" ) {
            _addWheelListener( elem, "MozMousePixelScroll", callback, useCapture );
        }
    };
    function _addWheelListener( elem, eventName, callback, useCapture ) {
        elem[ _addEventListener ]( prefix + eventName, support == "wheel" ? callback : function( originalEvent ) {
            !originalEvent && ( originalEvent = window.event );
            // create a normalized event object
            var event = {
                // keep a ref to the original event object
                originalEvent: originalEvent,
                target: originalEvent.target || originalEvent.srcElement,
                type: "wheel",
                deltaMode: originalEvent.type == "MozMousePixelScroll" ? 0 : 1,
                deltaX: 0,
                deltaY: 0,
                deltaZ: 0,
                preventDefault: function() {
                    originalEvent.preventDefault ?
                        originalEvent.preventDefault() :
                        originalEvent.returnValue = false;
                }
            };
            
            // calculate deltaY (and deltaX) according to the event
            if ( support == "mousewheel" ) {
                event.deltaY = - 1/40 * originalEvent.wheelDelta;
                // Webkit also support wheelDeltaX
                originalEvent.wheelDeltaX && ( event.deltaX = - 1/40 * originalEvent.wheelDeltaX );
            } else {
                event.deltaY = originalEvent.deltaY || originalEvent.detail;
            }
            // it's time to fire the callback
            return callback( event );
        }, useCapture || false );
    }
})(window,document);

Gecko notes

The event order with legacy mouse scroll events

If a trusted wheel event is not consumed, a DOMMouseScroll event and a MozMousePixelScroll event are fired for backward compatibility. Their attribute values are computed from the wheel event's delta values and the nearest ancestor clipped element (i.e., overflow is not visible). If either wheel event or one of the legacy events is consumed by event.preventDefault(), nothing happens.

The event order is:

1. A wheel event in the default event group (both web applications and add-ons can handle the events in this group)
2. A vertical DOMMouseScroll event in both event group if accumulated deltaY of consecutive wheel events become larger than 1.0 or less than -1.0
3. A vertical MozMousePixelScroll event in both event group if deltaY of the latest wheel event isn't zero
4. A horizontal DOMMouseScroll event in both event group if accumulated deltaX of consecutive wheel events become larger than 1.0 or less than -1.0
5. A horizontal MozMousePixelScroll event in both event group if deltaX of the latest wheel event isn't zero
6. A wheel event in the system group (only add-ons can handle in this group)

If an Add-on needs to know if one of legacy events are consumed by web contents, it can use the wheel event of #6. See the document of nsIEventListenerService for the detail of system event group.

The delta values and default action of trusted events can be customized by user preferences (details). Therefore, any web developers shouldn't expect a particular action would occur after receiving this event.

The delta values

The delta values do not indicate the actual scroll amount by default. If the user was holding a modifier key when moving the scroll wheel, the wheel action may cause another action such as moving forward or backward through browser history or zooming in or out. In addition, even when scrolling, the scrolled element may be different from its event target. The wheel event target is computed only from the mouse cursor position at the time at which the event was fired. That event may not only not be the one actually being scrolled, but may not even be scrollable.

The deltaMode value

On Windows, following 3 native events cause DOM wheel events.

WM_MOUSEWHEEL (Vertical mouse wheel event)

The deltaMode can be DOM_DELTA_LINE or DOM_DELTA_PAGE. It depends on user settings of Windows (The defualt setting causes DOM_DELTA_LINE).

WM_MOUSEHWHEEL (Horizontal mouse wheel event)

The deltaMode can be DOM_DELTA_LINE or DOM_DELTA_PAGE. However, neither wheel scroll speed setting dialog of Windows nor similar UI of each mouse driver's utility typically has the UI to change to page scroll. So, typically, this value is DOM_DELTA_LINE.

WM_GESTURE (Only when caused by panning)

The deltaMode is always DOM_DELTA_PIXEL. But note that most touchpad devices of notebook emulate mouse wheel events rather than using this event. This event it typically used on tablet PC.

On Mac, deltaMode value depends on the device. If the device supports high resolution scroll by pixels, deltaMode value is typically DOM_DELTA_PIXEL. However, the user can change it to DOM_DELTA_LINE with "mousewheel.enable_pixel_scrolling" pref.  If the device doesn't support high resolution scroll, it's always DOM_DELTA_LINE.

On other platforms, the deltaMode value is always DOM_DELTA_LINE.

Untrusted events

Untrusted wheel events never cause any default action.

See also

• WheelEvent
• Gecko's legacy events: DOMMouseScroll and MozMousePixelScroll
• Non-Gecko browsers' legacy event: mousewheel
• WebKit bug: https://bugs.webkit.org/show_bug.cgi?id=94081