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. Show
scroll event Please keep in mind that the default action of a wheel event is implementation-defined — a wheel event doesn't necessarily dispatch a scroll event. Even if it does, that doesn't mean that the delta values in the wheel event must reflect the content's scrolling direction. So do not rely on delta properties to get the content's scrolling direction — instead detect value changes of scrollLeft and scrollTop in a scroll event. Interface WheelEvent Synchronicity asynchronous Bubbles Yes Cancelable Yes Target defaultView, Document, Element Default Action Scroll, moving history, or zooming in/out.PropertiesThis event implements the properties of WheelEvent, MouseEvent, UIEvent and Event. Properties of WheelEventThis 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:
Properties of MouseEventThis interface also inherits properties of its parents, UIEvent and Event. 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 onlyThe 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 onlyThe 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.clientYProperties of UIEventThis 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 EventEvent.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.srcElement A non-standard alias (from old versions of Microsoft Internet Explorer) for Event.target, which is starting to be supported in some other browsers for web compatibility purposes. 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).Obsolete propertiesEvent.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.MethodsThis event implements the methods of WheelEvent, MouseEvent, UIEvent and Event. Methods of WheelEventThis interface doesn't define any methods, but inherits methods from its parents, MouseEvent, UIEvent and Event. Methods of MouseEventThis 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 UIEventThis 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 EventEvent.createEvent()Creates a new event, which must then be initialized by calling its initEvent() method. Event.composedPath() Returns the event’s path (objects on which listeners will be invoked). This does not include nodes in shadow trees if the shadow root was created with its ShadowRoot.mode closed. Event.initEvent() Initializes the value of an Event created. If the event has already being dispatched, this method does nothing. 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.Obsolete methodsEvent.getPreventDefault() Non-standard. Returns the value of Event.defaultPrevented. Use Event.defaultPrevented instead. 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.SpecificationsBrowser compatibilityWe're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!
[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 browserThe 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 notesIf 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:
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 valuesThe 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 valueOn 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 eventsUntrusted wheel events never cause any default action. See also |