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) and1.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.detail
Read 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.view
Read 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 totrue
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 DOMNode
s 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()
andEvent.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 tocomposed
. 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
. UseEvent.defaultPrevented
instead.
Specifications
Specification | Status | Comment |
---|---|---|
Document Object Model (DOM) Level 3 Events Specification The definition of 'wheel' in that specification. |
Working Draft | 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 accumulateddeltaY
of consecutivewheel
events become larger than 1.0 or less than -1.0 - A vertical
MozMousePixelScroll
event in both event group ifdeltaY
of the latestwheel
event isn't zero - A horizontal
DOMMouseScroll
event in both event group if accumulateddeltaX
of consecutivewheel
events become larger than 1.0 or less than -1.0 - A horizontal
MozMousePixelScroll
event in both event group ifdeltaX
of the latestwheel
event isn't zero - A
wheel
event in the system group (only add-ons can handle in this group)
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 beDOM_DELTA_LINE
orDOM_DELTA_PAGE
. It depends on user settings of Windows (The defualt setting causesDOM_DELTA_LINE
). - WM_MOUSEHWHEEL (Horizontal mouse wheel event)
- The
deltaMode
can beDOM_DELTA_LINE
orDOM_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 isDOM_DELTA_LINE
. - WM_GESTURE (Only when caused by panning)
- The
deltaMode
is alwaysDOM_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
andMozMousePixelScroll
- Non-Gecko browsers' legacy event:
mousewheel
- WebKit bug: https://bugs.webkit.org/show_bug.cgi?id=94081