wheel

  • Revision slug: DOM/Mozilla_event_reference/wheel
  • Revision title: wheel
  • Revision id: 391711
  • Created:
  • Creator: segdeha
  • Is current revision? No
  • Comment

Revision Content

The wheel event is fired when a wheel button of a pointing device (usually a mouse) is rotated. This event deprecates the legacy mousewheel event.

General info

Specification
DOM L3
Interface
WheelEvent
Synchronicity
asynchronous
Bubbles
Yes
Cancelable
Yes
Target
defaultView, Document, Element
Default Action
Scroll, moving history, or zooming in/out.

Properties

{{OpenEventProperties()}}{{UIEventProperties()}}{{MouseEventProperties()}}{{WheelEventProperties()}}{{CloseEventProperties()}}

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support {{ CompatNo() }} {{ CompatGeckoDesktop("17.0") }} {{ CompatIE("9.0") }}[2] {{ CompatNo() }} {{ CompatUnknown() }}
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support {{ CompatUnknown() }} {{ CompatGeckoMobile("17.0") }} {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }}

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

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, onwheel, 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,
                delatZ: 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.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 {{ domeventxref("DOMMouseScroll") }} event and a {{ domeventxref("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 {{ domxref("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)
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.

See also

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

Revision Source

<p>The <code>wheel</code> event is fired when a wheel button of a pointing device (usually a mouse) is rotated. This event deprecates the legacy <a href="/en-US/docs/DOM/DOM_event_reference/mousewheel" title="/en-US/docs/DOM/DOM_event_reference/mousewheel">mousewheel</a> event.</p>
<h2 id="General_info">General info</h2>
<dl>
  <dt style="float: left; text-align: right; width: 120px;">
    Specification</dt>
  <dd style="margin: 0 0 0 120px;">
    <a class="external" href="http://www.w3.org/TR/DOM-Level-3-Events/#event-type-wheel">DOM L3</a></dd>
  <dt style="float: left; text-align: right; width: 120px;">
    Interface</dt>
  <dd style="margin: 0 0 0 120px;">
    <code><a href="https://developer.mozilla.org/en-US/docs/DOM/WheelEvent" title="/en-US/docs/DOM/WheelEvent">WheelEvent</a></code></dd>
  <dt style="float: left; text-align: right; width: 120px;">
    Synchronicity</dt>
  <dd style="margin: 0 0 0 120px;">
    asynchronous</dd>
  <dt style="float: left; text-align: right; width: 120px;">
    Bubbles</dt>
  <dd style="margin: 0 0 0 120px;">
    Yes</dd>
  <dt style="float: left; text-align: right; width: 120px;">
    Cancelable</dt>
  <dd style="margin: 0 0 0 120px;">
    Yes</dd>
  <dt style="float: left; text-align: right; width: 120px;">
    Target</dt>
  <dd style="margin: 0 0 0 120px;">
    defaultView, Document, Element</dd>
  <dt style="float: left; text-align: right; width: 120px;">
    Default Action</dt>
  <dd style="margin: 0 0 0 120px;">
    Scroll, moving history, or zooming in/out.</dd>
</dl>
<h2 id="Properties">Properties</h2>
<p>{{OpenEventProperties()}}{{UIEventProperties()}}{{MouseEventProperties()}}{{WheelEventProperties()}}{{CloseEventProperties()}}</p>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Chrome</th>
        <th>Firefox (Gecko)</th>
        <th>Internet Explorer</th>
        <th>Opera</th>
        <th>Safari</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatGeckoDesktop("17.0") }}</td>
        <td>{{ CompatIE("9.0") }}<sup><a href="#bc1">[2]</a></sup></td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatUnknown() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<div id="compat-mobile">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Android</th>
        <th>Firefox Mobile (Gecko)</th>
        <th>IE Mobile</th>
        <th>Opera Mobile</th>
        <th>Safari Mobile</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatGeckoMobile("17.0") }}</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatUnknown() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<p><sup><a name="bc1">[1]</a></sup> Internet Explorer exposes the <code>wheel</code> event only via <code>addEventListener</code>, there is no <code>onwheel</code> attribute on DOM objects. <a href="https://connect.microsoft.com/IE/feedback/details/782835/missing-onwheel-attribute-for-the-wheel-event-although-its-supported-via-addeventlistener">Bug report.</a></p>
<h3 id="Listening_to_this_event_across_browser">Listening to this event across browser</h3>
<p>The following script creates a global <code>addWheelListener</code> method that allows to listen to the different wheel events across browsers and prevent the default behavior.</p>
<pre class="brush:js;">
// creates a global "addWheelListener" method
// example: addWheelListener( elem, function( e ) { console.log( e.deltaY ); e.preventDefault(); } );
(function(window,document) {

&nbsp;&nbsp;&nbsp; var prefix = "", _addEventListener, onwheel, support;

&nbsp;&nbsp;&nbsp; // detect event model
&nbsp;&nbsp;&nbsp; if ( window.addEventListener ) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; _addEventListener = "addEventListener";
&nbsp;&nbsp;&nbsp; } else {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; _addEventListener = "attachEvent";
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; prefix = "on";
&nbsp;&nbsp;&nbsp; }

&nbsp;&nbsp;&nbsp; // 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

&nbsp;&nbsp;&nbsp; window.addWheelListener = function( elem, callback, useCapture ) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; _addWheelListener( elem, support, callback, useCapture );

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // handle MozMousePixelScroll in older Firefox
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if( support == "DOMMouseScroll" ) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; _addWheelListener( elem, "MozMousePixelScroll", callback, useCapture );
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }
&nbsp;&nbsp;&nbsp; };

&nbsp;&nbsp;&nbsp; function _addWheelListener( elem, eventName, callback, useCapture ) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; elem[ _addEventListener ]( prefix + eventName, support == "wheel" ? callback : function( originalEvent ) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; !originalEvent &amp;&amp; ( originalEvent = window.event );

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // create a normalized event object
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; var event = {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // keep a ref to the original event object
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; originalEvent: originalEvent,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; target: originalEvent.target || originalEvent.srcElement,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; type: "wheel",
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; deltaMode: originalEvent.type == "MozMousePixelScroll" ? 0 : 1,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; deltaX: 0,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; delatZ: 0,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; preventDefault: function() {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; originalEvent.preventDefault ?
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; originalEvent.preventDefault() :
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; originalEvent.returnValue = false;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; };
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // calculate deltaY (and deltaX) according to the event
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if ( support == "mousewheel" ) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; event.deltaY = - 1/40 * originalEvent.wheelDelta;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // Webkit also support wheelDeltaX
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; originalEvent.wheelDeltaX &amp;&amp; ( event.deltaX = - 1/40 * originalEvent.wheelDeltaX );
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; } else {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; event.deltaY = originalEvent.detail;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; // it's time to fire the callback
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return callback( event );

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }, useCapture || false );
&nbsp;&nbsp;&nbsp; }

})(window,document);</pre>
<h2 id="Gecko_notes">Gecko notes</h2>
<h3 id="The_event_order_with_legacy_mouse_scroll_events">The event order with legacy mouse scroll events</h3>
<p>If a trusted <code>wheel</code> event is not consumed, a {{ domeventxref("DOMMouseScroll") }} event and a {{ domeventxref("MozMousePixelScroll") }} event are fired for backward compatibility. Their attribute values are computed from the <code>wheel</code> event's delta values and the nearest ancestor clipped element (i.e., <a href="/en/CSS/overflow" title="en/CSS/overflow"><code>overflow</code></a> is not visible). If either <code>wheel</code> event or one of the legacy events is consumed by {{ domxref("event.preventDefault()") }}, nothing happens.</p>
<p>The event order is:</p>
<ol>
  <li>A <code>wheel</code> event in the default event group (both web applications and add-ons can handle the events in this group)</li>
  <li>A vertical <code>DOMMouseScroll</code> event in both event group if accumulated <code>deltaY</code> of consecutive <code>wheel</code> events become larger than 1.0 or less than -1.0</li>
  <li>A vertical <code>MozMousePixelScroll</code> event in both event group if <code>deltaY</code> of the latest <code>wheel</code> event isn't zero</li>
  <li>A horizontal <code>DOMMouseScroll</code> event in both event group if accumulated <code>deltaX</code> of consecutive <code>wheel</code> events become larger than 1.0 or less than -1.0</li>
  <li>A horizontal <code>MozMousePixelScroll</code> event in both event group if <code>deltaX</code> of the latest <code>wheel</code> event isn't zero</li>
  <li>A <code>wheel</code> event in the system group (only add-ons can handle in this group)</li>
</ol>
<table align="center">
  <caption>
    What happens if <code>preventDefault()</code> of each event called?</caption>
  <thead>
  </thead>
  <tbody>
    <tr>
      <th scope="row"><code>wheel</code> (default event group)</th>
      <td><code>preventDefault()</code> called</td>
      <td>&nbsp;</td>
      <td>&nbsp;</td>
      <td>&nbsp;</td>
      <td>&nbsp;</td>
    </tr>
    <tr>
      <th scope="row"><code>DOMMouseScroll</code> (Vertical)</th>
      <td>Not fired</td>
      <td><code>preventDefault()</code> called</td>
      <td>&nbsp;</td>
      <td>&nbsp;</td>
      <td>&nbsp;</td>
    </tr>
    <tr>
      <th scope="row"><code>MozMousePixelScroll</code> (Vertical)</th>
      <td>Not fired</td>
      <td><code>defaultPrevented</code> is true</td>
      <td><code>preventDefault()</code> called</td>
      <td>&nbsp;</td>
      <td>&nbsp;</td>
    </tr>
    <tr>
      <th scope="row"><code>DOMMouseScroll</code> (Horizontal)</th>
      <td>Not fired</td>
      <td>Not affected</td>
      <td>Not affected</td>
      <td><code>preventDefault()</code> called</td>
      <td>&nbsp;</td>
    </tr>
    <tr>
      <th scope="row"><code>MozMousePixelScroll</code> (Horizontal)</th>
      <td>Not fired</td>
      <td>Not affected</td>
      <td>Not affected</td>
      <td><code>defaultPrevented</code> is true</td>
      <td><code>preventDefault()</code> called</td>
    </tr>
    <tr>
      <th scope="row"><code>wheel</code> (system event group)</th>
      <td><code>defaultPrevented</code> is true</td>
      <td><code>defaultPrevented</code> is true</td>
      <td><code>defaultPrevented</code> is true</td>
      <td><code>defaultPrevented</code> is true</td>
      <td><code>defaultPrevented</code> is true</td>
    </tr>
  </tbody>
</table>
<p>If an Add-on needs to know if one of legacy events are consumed by web contents, it can use the <code>wheel</code> event of #6. See the document of <a href="/en-US/docs/XPCOM_Interface_Reference/nsIEventListenerService" title="/en-US/docs/XPCOM_Interface_Reference/nsIEventListenerService"><code>nsIEventListenerService</code></a> for the detail of system event group.</p>
<p>The delta values and default action of trusted events can be customized by user preferences (<a href="https://wiki.mozilla.org/Gecko:Mouse_Wheel_Scrolling#Preferences_for_customizing_delta_values_and_default_action" title="/en-US/docs/HTML/Element/details">details</a>). Therefore, any web developers shouldn't expect a particular action would occur after receiving this event.</p>
<h3 id="The_delta_values">The delta values</h3>
<p>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.</p>
<h3 id="The_deltaMode_value">The deltaMode value</h3>
<p>On Windows, following 3 native events cause DOM <code>wheel</code> events.</p>
<dl>
  <dt>
    WM_MOUSEWHEEL (Vertical mouse wheel event)</dt>
  <dd>
    The <code>deltaMode</code> can be <code>DOM_DELTA_LINE</code> or <code>DOM_DELTA_PAGE</code>. It depends on user settings of Windows (The defualt setting causes <code>DOM_DELTA_LINE</code>).</dd>
  <dt>
    WM_MOUSEHWHEEL (Horizontal mouse wheel event)</dt>
  <dd>
    The <code>deltaMode</code> can be <code>DOM_DELTA_LINE</code> or <code>DOM_DELTA_PAGE</code>. 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 <code>DOM_DELTA_LINE</code>.</dd>
  <dt>
    WM_GESTURE (Only when caused by panning)</dt>
  <dd>
    The <code>deltaMode</code> is always <code>DOM_DELTA_PIXEL</code>. 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.</dd>
</dl>
<p>On Mac, <code>deltaMode</code> value depends on the device. If the device supports high resolution scroll by pixels, <code>deltaMode</code> value is typically <code>DOM_DELTA_PIXEL</code>. However, the user can change it to <code>DOM_DELTA_LINE</code> with <code>"mousewheel.enable_pixel_scrolling"</code> pref.&nbsp; If the device doesn't support high resolution scroll, it's always <code>DOM_DELTA_LINE</code>.</p>
<p>On other platforms, the <code>deltaMode</code> value is always <code>DOM_DELTA_LINE</code>.</p>
<h3 id="Untrusted_events">Untrusted events</h3>
<p>Untrusted <code>wheel</code> events never cause any default action.</p>
<h2 id="See_also">See also</h2>
<ul>
  <li>{{ domxref("WheelEvent") }}</li>
  <li>Gecko's legacy events: {{ domeventxref("DOMMouseScroll") }} and {{ domeventxref("MozMousePixelScroll") }}</li>
  <li>Non-Gecko browsers' legacy event: {{ domeventxref("mousewheel") }}</li>
  <li>WebKit bug:&nbsp;<a href="https://bugs.webkit.org/show_bug.cgi?id=94081" title="https://bugs.webkit.org/show_bug.cgi?id=94081">https://bugs.webkit.org/show_bug.cgi?id=94081</a></li>
</ul>
Revert to this revision