W3cubDocs

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 (if applicable) when the mouse event was fired.
MouseEvent.buttons Read only: The buttons being depressed (if any) 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; 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

Specification	Status	Comment
Document Object Model (DOM) Level 3 Events Specification The definition of 'wheel' in that specification.	Obsolete	Initial definition.

Browser compatibility

Feature	Chrome	Edge	Firefox (Gecko)	Internet Explorer	Opera	Safari
Basic support	31	(Yes)	17.0 (17.0)	9.0^[1]	18	7.0
Pinch-to-zoom maps to `WheelEvent` + `Ctrl` key^[2]	(Yes)	?	55.0 (55.0)	?	?	?

Feature	Android	Edge	Firefox Mobile (Gecko)	IE Mobile	Opera Mobile	Safari Mobile
Basic support	?	(Yes)	17.0 (17.0)	?	?	?
Pinch-to-zoom maps to `WheelEvent` + `Ctrl` key^[2]	?	?	55.0 (55.0)	?	?	?

[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:

A wheel event in the default event group (both web applications and add-ons can handle the events in this group)
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
A vertical MozMousePixelScroll event in both event group if deltaY of the latest wheel event isn't zero
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
A horizontal MozMousePixelScroll event in both event group if deltaX of the latest wheel event isn't zero
A wheel event in the system group (only add-ons can handle in this group)

What happens if `preventDefault()` of each event called?
`wheel` (default event group)	`preventDefault()` called
`DOMMouseScroll` (Vertical)	Not fired	`preventDefault()` called
`MozMousePixelScroll` (Vertical)	Not fired	`defaultPrevented` is true	`preventDefault()` called
`DOMMouseScroll` (Horizontal)	Not fired	Not affected	Not affected	`preventDefault()` called
`MozMousePixelScroll` (Horizontal)	Not fired	Not affected	Not affected	`defaultPrevented` is true	`preventDefault()` called
`wheel` (system event group)	`defaultPrevented` is true	`defaultPrevented` is true	`defaultPrevented` is true	`defaultPrevented` is true	`defaultPrevented` is true

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.

wheel

General info

Properties

Properties of WheelEvent

Properties of MouseEvent

Properties of UIEvent

Properties of Event