The mouse event module originates from the [[HTML401]]onclick,ondblclick,onmousedown,onmouseup,onmouseover,onmousemove, andonmouseout attributes. This event module is specifically designed for use with pointing input devices, such as a mouse or a trackball.

Interface MouseEvent

The {{MouseEvent}} interface provides specific contextual information associated with Mouse events.

In the case of nested elements, mouse events are always targeted at the most deeply nested element.

Ancestors of the targeted element can use event bubbling to obtain notifications of mouse events which occur within their descendent elements.

To create an instance of the {{MouseEvent}} interface, use the {{MouseEvent}} constructor, passing an optional {{MouseEventInit}} dictionary.

When initializing {{MouseEvent}} objects usinginitMouseEvent,implementations can use the client coordinates {{MouseEvent/clientX}} and {{MouseEvent/clientY}} for calculation of other coordinates (suchas target coordinates exposed by DOM Level 0 implementations orother proprietary attributes, e.g.,pageX).

MouseEvent

MouseEventInit

Implementations MUST maintain thecurrent click count when generating mouse events. This MUST be a non-negative integer indicating the number of consecutive clicks of a pointing device button within a specific time. The delay after which the count resets is specific to the environment configuration.

MouseEvent Algorithms

Native OS Requirements

The algorithms in this section assume that the native platform OS will provide the following:

Constructing Mouse Events

Generally, when a constructor of an {{Event}} interface, or of an interface inherited from the {{Event}} interface, is invoked, the steps described in [[DOM]] should be followed. However the {{MouseEvent}} interfaces provide additional dictionary members for initializing the internal state of the {{Event}} object's key modifiers: specifically, the internal state queried for using the {{MouseEvent/getModifierState()}} methods. This section supplements the [[DOM]] steps for intializing a new {{MouseEvent}} object with these optional modifier states.

For the purposes of constructing a {{MouseEvent}}, or object derived from these objects using the algorithm below, all {{MouseEvent}}, and derived objects haveinternal key modifier state which can be set and retrieved using thekey modifier names described in theModifier Keys table in [[UIEvents-Key]].

The following steps supplement the algorithm defined for constructing events in [[DOM]]:

Global State for MouseEvent

User Agent-Level State

The UA must maintain the following values that are shared for the entire User Agent.

Window-Level State

Alast mouse element value (initially undefined) that keeps track of the last {{Element}} that we sent a MouseEvent to.

Alast mouse DOM path value (initially empty) that contains a snapshot of the ancestors {{Element}}s of thelast mouse element when the most recent mouse event was sent.

Internal State for MouseEvent

A {{MouseEvent}} has the following internal flags that are used to track the state of various modifier keys:shift flag,control flag,alt flag,altgraph flag,andmeta flag.These flags are set if the corresponding modifier key was pressed at the timeof the mouse event.

hit test

initialize a {{MouseEvent}}

set mouse event modifiers

create a cancelable MouseEvent

create a non-cancelable MouseEvent

calculate MouseEvent button attribute

This will return a button ID suitable for storing in the {{MouseEvent}}'s {{MouseEvent/button}} attribute.

set MouseEvent attributes from native

handle native mouse down

handle native mouse up

handle native mouse click

send click event

handle native mouse double click

handle native mouse move

maybe show context menu

To handle a context menu triggered by the keyboard, call this algorithm with |native| = null and |target| = currently focused element.

Mouse Event Order

Certain mouse events defined in this specification MUST occur in a set order relative to one another. The following shows the event sequence that MUST occur when a pointing device's cursor is moved over an element:

#	Event Type	Element	Notes
1	{{mousemove}}
			Pointing device is moved into element A...
2	{{mouseover}}	A
3	{{mouseenter}}	A
4	{{mousemove}}	A	Multiple {{mousemove}} events
			Pointing device is moved out of element A...
5	{{mouseout}}	A
6	{{mouseleave}}	A

When a pointing device is moved into an elementA, and then into a nested elementB and then back out again, the following sequence of events MUST occur:

Sometimes elements can be visually overlapped using CSS. In the following example, three elements labeled A, B, and C all have the same dimensions and absolute position on a web page. Element C is a child of B, and B is a child of A in the DOM:

When the pointing device is moved from outside the element stack to the element labeled C and then moved out again, the following series of events MUST occur:

The {{mouseover}}/{{mouseout}} events are only fired once, while {{mouseenter}}/{{mouseleave}} events are fired three times (once to each element).

The following is the typical sequence of events when a button associated with a pointing device (e.g., a mouse button or trackpad) is pressed and released over an element:

The lag time, degree, distance, and number of {{mousemove}} events allowed between the {{mousedown}} and {{mouseup}} events while still firing a {{click}} or {{dblclick}} event will be implementation-, device-, and platform-specific. This tolerance can aid users that have physical disabilities like unsteady hands when these users interact with a pointing device.

	Event Type	Element	Notes
1	{{mousemove}}
			Pointing device is moved into element A...
2	{{mouseover}}	A
3	{{mouseenter}}	A
4	{{mousemove}}	A	Multiple {{mousemove}} events
			Pointing device is moved into nested element B...
5	{{mouseout}}	A
6	{{mouseover}}	B
7	{{mouseenter}}	B
8	{{mousemove}}	B	Multiple {{mousemove}} events
			Pointing device is moved from element B into A...
9	{{mouseout}}	B
10	{{mouseleave}}	B
11	{{mouseover}}	A
12	{{mousemove}}	A	Multiple {{mousemove}} events
			Pointing device is moved out of element A...
13	{{mouseout}}	A
14	{{mouseleave}}	A

	Event Type	Element	Notes
1	{{mousemove}}
			Pointing device is moved into element C, the topmost element in the stack
2	{{mouseover}}	C
3	{{mouseenter}}	A
4	{{mouseenter}}	B
5	{{mouseenter}}	C
6	{{mousemove}}	C	Multiple {{mousemove}} events
			Pointing device is moved out of element C...
7	{{mouseout}}	C
8	{{mouseleave}}	C
9	{{mouseleave}}	B
10	{{mouseleave}}	A

	Event Type	Notes
1	{{mousedown}}
2	{{mousemove}}	OPTIONAL, multiple events, some limits
3	{{mouseup}}
4	{{click}}
5	{{mousemove}}	OPTIONAL, multiple events, some limits
6	{{mousedown}}
7	{{mousemove}}	OPTIONAL, multiple events, some limits
8	{{mouseup}}
9	{{click}}
10	{{dblclick}}

Each implementation will determine the appropriatehysteresistolerance, but in general SHOULD fire {{click}} and {{dblclick}}events when the event target of the associated {{mousedown}} and{{mouseup}} events is the same element with no {{mouseout}} or{{mouseleave}} events intervening, and SHOULD fire {{click}} and{{dblclick}} events on the nearest common inclusive ancestor when theassociated {{mousedown}} and {{mouseup}} event targets aredifferent.

If a {{mousedown}} event was targeted at an HTML document'sbodyelement, and the corresponding {{mouseup}} event was targeted atthedocument element, then the {{click}} event will be dispatchedto thedocument element, since it is the nearest common inclusiveancestor.

If the [=Event/target=] (e.g. the target element) is removed from theDOM during the mouse events sequence, the remaining events of thesequence MUST NOT be fired on that element.

If the target element is removed from the DOM as the result of a{{mousedown}} event, no events for that element will be dispatchedfor {{mouseup}}, {{click}}, or {{dblclick}}, nor any defaultactivation events. However, the {{mouseup}} event will still bedispatched on the element that is exposed to the mouse after the removalof the initial target element. Similarly, if the target element isremoved from the DOM during the dispatch of a {{mouseup}} event, the{{click}} and subsequent events will not be dispatched.

Mouse Event Types

auxclick

Type	`auxclick`
Interface	{{PointerEvent}}
Sync / Async	Sync
Bubbles	Yes
Trusted Targets	`Element`
Cancelable	Yes
Composed	Yes
Default action	Varies
Context (trusted events)	{{Event.target}} : [=topmost event target=] {{UIEvent.view}} : {{Window}} {{UIEvent.detail}} : indicates the [=current click count=]; the attribute value MUST be`1` when the user begins this action and increments by`1` for each click. {{MouseEvent.screenX}} : value based on the pointer position on the screen {{MouseEvent.screenY}} : value based on the pointer position on the screen {{MouseEvent.clientX}} : value based on the pointer position within the viewport {{MouseEvent.clientY}} : value based on the pointer position within the viewport {{MouseEvent.layerX}} : value based on the pointer position within the containing element {{MouseEvent.layerY}} : value based on the pointer position within the containing element {{MouseEvent.altKey}} :`true` if`Alt` modifier was active, otherwise`false` {{MouseEvent.ctrlKey}} :`true` if`Control` modifier was active, otherwise`false` {{MouseEvent.shiftKey}} :`true` if`Shift` modifier was active, otherwise`false` {{MouseEvent.metaKey}} :`true` if`Meta` modifier was active, otherwise`false` {{MouseEvent.button}} : value based on current button pressed {{MouseEvent.buttons}} : value based on all buttons currently depressed,`0` if no buttons pressed {{MouseEvent.relatedTarget}} :`null` For {{PointerEvent}} specific attributes, see the [[PointerEvents]] spec.

The {{auxclick}} event type MUST be dispatched on thetopmostevent target indicated by the pointer, when the user pressesdown and releases the non-primary pointer button, or otherwise activatesthe pointer in a manner that simulates such an action. The actuationmethod of the mouse button depends upon the pointer device and theenvironment configuration, e.g., it MAY depend on the screenlocation or the delay between the press and release of the pointingdevice button.

The {{auxclick}} event should only be fired for the non-primary pointerbuttons (i.e., when {{MouseEvent/button}} value is not0,{{MouseEvent/buttons}} value is greater than1). The primary button(like the left button on a standard mouse) MUST NOT fire{{auxclick}} events. See {{click}} for a corresponding event thatis associated with the primary button.

The {{auxclick}} event MAY be preceded by the {{mousedown}} and{{mouseup}} events on the same element, disregarding changesbetween other node types (e.g., text nodes). Depending upon theenvironment configuration, the {{auxclick}} event MAY be dispatchedif one or more of the event types {{mouseover}},{{mousemove}}, and {{mouseout}} occur between the press andrelease of the pointing device button.

Thedefault action of the {{auxclick}} event type variesbased on the [=Event/target=] of the event and the value of the{{MouseEvent/button}} or {{MouseEvent/buttons}} attributes. Typicaldefault actions of the {{auxclick}} event type are as follows:

In the case of right button, the {{auxclick}} event is dispatched afterany {{contextmenu}} event. Note that some user agents swallow all inputevents while a context menu is being displayed, so auxclick may not beavailable to applications in such scenarios.See for more clarification.

click

Type	`click`
Interface	{{PointerEvent}}
Sync / Async	Sync
Bubbles	Yes
Trusted Targets	`Element`
Cancelable	Yes
Composed	Yes
Default action	Varies
Context (trusted events)	{{Event.target}} : [=topmost event target=] {{UIEvent.view}} : {{Window}} {{UIEvent.detail}} : indicates the [=current click count=]; the attribute value MUST be`1` when the user begins this action and increments by`1` for each click. {{MouseEvent.screenX}} : value based on the pointer position on the screen {{MouseEvent.screenY}} : value based on the pointer position on the screen {{MouseEvent.clientX}} : value based on the pointer position within the viewport {{MouseEvent.clientY}} : value based on the pointer position within the viewport {{MouseEvent.layerX}} : value based on the pointer position within the containing element {{MouseEvent.layerY}} : value based on the pointer position within the containing element {{MouseEvent.altKey}} :`true` if`Alt` modifier was active, otherwise`false` {{MouseEvent.ctrlKey}} :`true` if`Control` modifier was active, otherwise`false` {{MouseEvent.shiftKey}} :`true` if`Shift` modifier was active, otherwise`false` {{MouseEvent.metaKey}} :`true` if`Meta` modifier was active, otherwise`false` {{MouseEvent.button}} : value based on current button pressed {{MouseEvent.buttons}} : value based on all buttons currently depressed,`0` if no buttons pressed {{MouseEvent.relatedTarget}} :`null` For {{PointerEvent}} specific attributes, see the [PointerEvents] spec.

The {{click}} event type MUST be dispatched on thetopmostevent target indicated by the pointer, when the user pressesdown and releases the primary pointer button, or otherwise activatesthe pointer in a manner that simulates such an action. The actuationmethod of the mouse button depends upon the pointer device and theenvironment configuration, e.g., it MAY depend on the screenlocation or the delay between the press and release of the pointingdevice button.

The {{click}} event should only be fired for the primary pointerbutton (i.e., when {{MouseEvent/button}} value is0,{{MouseEvent/buttons}} value is1). Secondary buttons(like the middle or right button on a standard mouse) MUST NOT fire{{click}} events. See {{auxclick}} for a corresponding event thatis associated with the non-primary buttons.

The {{click}} event MAY be preceded by the {{mousedown}} and{{mouseup}} events on the same element, disregarding changesbetween other node types (e.g., text nodes). Depending upon theenvironment configuration, the {{click}} event MAY be dispatchedif one or more of the event types {{mouseover}},{{mousemove}}, and {{mouseout}} occur between the press andrelease of the pointing device button. The {{click}} event MAYalso be followed by the {{dblclick}} event.

If a user mouses down on a text node child of a<p> element which has been styled with a largeline-height, shifts the mouse slightly such that it is no longerover an area containing text but is still within the containingblock of that<p> element (i.e., the pointer isbetween lines of the same text block, but not over the text node perse), then subsequently mouses up, this will likely still trigger a{{click}} event (if it falls within the normal temporalhysteresis for a {{click}}), since the user has stayedwithin the scope of the same element. Note that user-agent-generatedmouse events are not dispatched on text nodes.

In addition to being associated with pointer devices, the{{click}} event type MUST be dispatched as part of an elementactivation.

For maximum accessibility, content authors are encouraged to use the{{click}} event type when defining activation behavior for customcontrols, rather than other pointing-device event types such as{{mousedown}} or {{mouseup}}, which are more device-specific.Though the {{click}} event type has its origins in pointerdevices (e.g., a mouse), subsequent implementation enhancements haveextended it beyond that association, and it can be considered adevice-independent event type for element activation.

Thedefault action of the {{click}} event type variesbased on the [=Event/target=] of the event and the value of the{{MouseEvent/button}} or {{MouseEvent/buttons}} attributes. Typicaldefault actions of the {{click}} event type are as follows:

contextmenu

When the {{contextmenu}} event is triggered by right mouse button, the{{contextmenu}} event MUST be dispatched after the {{mousedown}} event.

Depending on the platform, the {{contextmenu}} event may be dispatchedbefore or after the {{mouseup}} event.

Type	`contextmenu`
Interface	{{PointerEvent}}
Sync / Async	Sync
Bubbles	Yes
Trusted Targets	`Element`
Cancelable	Yes
Composed	Yes
Default action	Invoke a context menu if supported.
Context (trusted events)	{{Event}}.{{Event/target}} :topmost event target {{UIEvent}}.{{UIEvent/view}} : {{Window}} {{UIEvent}}.{{UIEvent/detail}} : 0 {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element {{MouseEvent}}.{{MouseEvent/altKey}} :`true` if`Alt` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/ctrlKey}} :`true` if`Control` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/shiftKey}} :`true` if`Shift`modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/metaKey}} :`true` if`Meta` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed,`0` if no buttons pressed {{MouseEvent}}.{{MouseEvent/relatedTarget}} :`null`

dblclick

Type	`dblclick`
Interface	{{MouseEvent}}
Sync / Async	Sync
Bubbles	Yes
Trusted Targets	`Element`
Cancelable	Yes
Composed	Yes
Default action	None
Context (trusted events)	{{UIEvent}}.{{UIEvent/view}} : {{Window}} {{UIEvent}}.{{UIEvent/detail}} : indicates thecurrent click count {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position on the screen {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position on the screen {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer position within the viewport {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer position within the viewport {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer position within the containing element {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer position within the containing element {{MouseEvent}}.{{MouseEvent/altKey}} :`true` if`Alt` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/ctrlKey}} :`true` if`Control` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/shiftKey}} :`true` if`Shift` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/metaKey}} :`true` if`Meta` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed,`0` if no buttons pressed {{MouseEvent}}.{{MouseEvent/relatedTarget}} :`null`

Auser agent MUST dispatch this event when the primary buttonof a pointing device is clicked twice over an element. Thedefinition of a double click depends on the environmentconfiguration, except that the event target MUST be the same between{{mousedown}}, {{mouseup}}, and {{dblclick}}. This eventtype MUST be dispatched after the event type {{click}} if a clickand double click occur simultaneously, and after the event type{{mouseup}} otherwise.

As with the {{click}} event, the {{dblclick}} event shouldonly be fired for the primary pointer button. Secondary buttons MUSTNOT fire {{dblclick}} events.

Canceling the {{click}} event does not affect the firing of a{{dblclick}} event.

mousedown

Type	`mousedown`
Interface	{{MouseEvent}}
Sync / Async	Sync
Bubbles	Yes
Trusted Targets	`Element`
Cancelable	Yes
Composed	Yes
Default action	Varies: Start a drag/drop operation; start a text selection; start a scroll/pan interaction (in combination with the middle mouse button, if supported)
Context (trusted events)	{{Event}}.{{Event/target}} :topmost event target {{UIEvent}}.{{UIEvent/view}} : {{Window}} {{UIEvent}}.{{UIEvent/detail}} : indicates thecurrent click count incremented by one. For example, if no click happened before the {{mousedown}}, {{UIEvent/detail}} will contain the value`1` {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position onthe screen {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position onthe screen {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer positionwithin the viewport {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer positionwithin the viewport {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer positionwithin the containing element {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer positionwithin the containing element {{MouseEvent}}.{{MouseEvent/altKey}} :`true` if`Alt` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/ctrlKey}} :`true` if`Control` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/shiftKey}} :`true` if`Shift` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/metaKey}} :`true` if`Meta` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed,`0` if no buttons pressed {{MouseEvent}}.{{MouseEvent/relatedTarget}} :`null`

Many implementations use the {{mousedown}} event to begin avariety of contextually dependentdefault actions. Thesedefault actions can be prevented if this event is canceled. Some ofthese default actions could include: beginning a drag/dropinteraction with an image or link, starting text selection, etc.Additionally, some implementations provide a mouse-driven panningfeature that is activated when the middle mouse button is pressed atthe time the {{mousedown}} event is dispatched.

mouseenter

Type	`mouseenter`
Interface	{{MouseEvent}}
Sync / Async	Sync
Bubbles	No
Trusted Targets	`Element`
Cancelable	No
Composed	No
Default action	None
Context (trusted events)	{{Event}}.{{Event/target}} :topmost event target {{UIEvent}}.{{UIEvent/view}} : {{Window}} {{UIEvent}}.{{UIEvent/detail}} :`0` {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position onthe screen {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position onthe screen {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer positionwithin the viewport {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer positionwithin the viewport {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer positionwithin the containing element {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer positionwithin the containing element {{MouseEvent}}.{{MouseEvent/altKey}} :`true` if`Alt` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/ctrlKey}} :`true` if`Control` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/shiftKey}} :`true` if`Shift` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/metaKey}} :`true` if`Meta` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/button}} :`0` {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed,`0` if no buttons pressed {{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the [=Event/target=] \| a pointing device is exiting, if any.

There are similarities between this event type and the CSS:hover pseudo-class [[CSS2]].See also the {{mouseleave}} event type.

mouseleave

Type	`mouseleave`
Interface	{{MouseEvent}}
Sync / Async	Sync
Bubbles	No
Trusted Targets	`Element`
Cancelable	No
Composed	No
Default action	None
Context (trusted events)	{{Event}}.{{Event/target}} :topmost event target {{UIEvent}}.{{UIEvent/view}} : {{Window}} {{UIEvent}}.{{UIEvent/detail}} :`0` {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position onthe screen {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position onthe screen {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer positionwithin the viewport {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer positionwithin the viewport {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer positionwithin the containing element {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer positionwithin the containing element {{MouseEvent}}.{{MouseEvent/altKey}} :`true` if`Alt` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/ctrlKey}} :`true` if`Control` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/shiftKey}} :`true` if`Shift` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/metaKey}} :`true` if`Meta` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/button}} :`0` {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed,`0` if no buttons pressed {{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the [=Event/target=] \| a pointing device is exiting, if any.

There are similarities between this event type and the CSS:hover pseudo-class [[CSS2]].See also the {{mouseenter}} event type.

mousemove

In some implementation environments, such as a browser,{{mousemove}} events can continue to fire if the user began adrag operation (e.g., a mouse button is pressed) and the pointingdevice has left the boundary of the user agent.

This event was formerly specified to be non-cancelable in DOM Level2 Events, but was changed to reflect existing interoperability betweenuser agents.

Type	`mousemove`
Interface	{{MouseEvent}}
Sync / Async	Sync
Bubbles	Yes
Trusted Targets	`Element`
Cancelable	Yes
Composed	Yes
Default action	None
Context (trusted events)	{{Event}}.{{Event/target}} :topmost event target {{UIEvent}}.{{UIEvent/view}} : {{Window}} {{UIEvent}}.{{UIEvent/detail}} :`0` {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position onthe screen {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position onthe screen {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer positionwithin the viewport {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer positionwithin the viewport {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer positionwithin the containing element {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer positionwithin the containing element {{MouseEvent}}.{{MouseEvent/altKey}} :`true` if`Alt` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/ctrlKey}} :`true` if`Control` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/shiftKey}} :`true` if`Shift` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/metaKey}} :`true` if`Meta` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/button}} :`0` {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed,`0` if no buttons pressed {{MouseEvent}}.{{MouseEvent/relatedTarget}} :`null`

mouseout

Type	`mouseout`
Interface	{{MouseEvent}}
Sync / Async	Sync
Bubbles	Yes
Trusted Targets	`Element`
Cancelable	Yes
Composed	Yes
Default action	None
Context (trusted events)	{{Event}}.{{Event/target}} :topmost event target {{UIEvent}}.{{UIEvent/view}} : {{Window}} {{UIEvent}}.{{UIEvent/detail}} :`0` {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position onthe screen {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position onthe screen {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer positionwithin the viewport {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer positionwithin the viewport {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer positionwithin the containing element {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer positionwithin the containing element {{MouseEvent}}.{{MouseEvent/altKey}} :`true` if`Alt` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/ctrlKey}} :`true` if`Control` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/shiftKey}} :`true` if`Shift` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/metaKey}} :`true` if`Meta` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/button}} :`0` {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed,`0` if no buttons pressed {{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the [=Event/target=] \| a pointing device is entering, if any.

mouseover

Type	`mouseover`
Interface	{{MouseEvent}}
Sync / Async	Sync
Bubbles	Yes
Trusted Targets	`Element`
Cancelable	Yes
Composed	Yes
Default action	None
Context (trusted events)	{{Event}}.{{Event/target}} :topmost event target {{UIEvent}}.{{UIEvent/view}} : {{Window}} {{UIEvent}}.{{UIEvent/detail}} :`0` {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position onthe screen {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position onthe screen {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer positionwithin the viewport {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer positionwithin the viewport {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer positionwithin the containing element {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer positionwithin the containing element {{MouseEvent}}.{{MouseEvent/altKey}} :`true` if`Alt` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/ctrlKey}} :`true` if`Control` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/shiftKey}} :`true` if`Shift` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/metaKey}} :`true` if`Meta` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/button}} :`0` {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed,`0` if no buttons pressed {{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the [=Event/target=] \| a pointing device is entering, if any.

mouseup

In some implementation environments, such as a browser, a{{mouseup}} event can be dispatched even if the pointing devicehas left the boundary of the user agent, e.g., if the user began adrag operation with a mouse button pressed.

Type	`mouseup`
Interface	{{MouseEvent}}
Sync / Async	Sync
Bubbles	Yes
Trusted Targets	`Element`
Cancelable	Yes
Composed	Yes
Default action	None
Context (trusted events)	{{Event}}.{{Event/target}} :topmost event target {{UIEvent}}.{{UIEvent/view}} : {{Window}} {{UIEvent}}.{{UIEvent/detail}} : indicates thecurrent click count incremented by one. {{MouseEvent}}.{{MouseEvent/screenX}} : value based on the pointer position onthe screen {{MouseEvent}}.{{MouseEvent/screenY}} : value based on the pointer position onthe screen {{MouseEvent}}.{{MouseEvent/clientX}} : value based on the pointer positionwithin the viewport {{MouseEvent}}.{{MouseEvent/clientY}} : value based on the pointer positionwithin the viewport {{MouseEvent}}.{{MouseEvent/layerX}} : value based on the pointer positionwithin the containing element {{MouseEvent}}.{{MouseEvent/layerY}} : value based on the pointer positionwithin the containing element {{MouseEvent}}.{{MouseEvent/altKey}} :`true` if`Alt` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/ctrlKey}} :`true` if`Control` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/shiftKey}} :`true` if`Shift` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/metaKey}} :`true` if`Meta` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/button}} : value based on current button pressed {{MouseEvent}}.{{MouseEvent/buttons}} : value based on all buttons currently depressed,`0` if no buttons pressed {{MouseEvent}}.{{MouseEvent/relatedTarget}} :`null`

Pointer Events and interfaces

`PointerEvent` interface

dictionary PointerEventInit : MouseEventInit {    long        pointerId = 0;    double      width = 1;    double      height = 1;    float       pressure = 0;    float       tangentialPressure = 0;    long        tiltX;    long        tiltY;    long        twist = 0;    double      altitudeAngle;    double      azimuthAngle;    DOMString   pointerType = "";    boolean     isPrimary = false;    long        persistentDeviceId = 0;    sequence<PointerEvent> coalescedEvents = [];    sequence<PointerEvent> predictedEvents = [];};[Exposed=Window]interface PointerEvent : MouseEvent {    constructor(DOMString type, optional PointerEventInit eventInitDict = {});    readonly        attribute long        pointerId;    readonly        attribute double      width;    readonly        attribute double      height;    readonly        attribute float       pressure;    readonly        attribute float       tangentialPressure;    readonly        attribute long        tiltX;    readonly        attribute long        tiltY;    readonly        attribute long        twist;    readonly        attribute double      altitudeAngle;    readonly        attribute double      azimuthAngle;    readonly        attribute DOMString   pointerType;    readonly        attribute boolean     isPrimary;    readonly        attribute long        persistentDeviceId;    [SecureContext] sequence<PointerEvent> getCoalescedEvents();    sequence<PointerEvent> getPredictedEvents();};

pointerId

A unique identifier for the pointer causing the event.user agents MAY reserve a generic {{pointerId}} value of0 or1 for the primary mouse pointer. The {{pointerId}} value of-1 MUST be reserved and used to indicate events that were generated by something other than a pointing device. For any other pointers, user agents are free to implement different strategies and approaches in how they assign a {{pointerId}} value. However, allactive pointers in the [=top-level browsing context=] (as defined by [[HTML]]) must be unique, and the identifier MUST NOT be influenced by any other top-level browsing context (i.e. one top-level browsing context cannot assume that the {{pointerId}} of a pointer will be the same when the pointer moves outside of the browsing context and into another top-level browsing context).

Theuser agent MAY recycle previously retired values for {{pointerId}} from previous active pointers, or it MAY always reuse the same {{pointerId}} for a particular pointing device (for instance, to uniquely identify particular pen/stylus inputs from a specific user in a multi-user collaborative application). However, in the latter case, to minimize the chance of fingerprinting and tracking across different pages or domains, the {{pointerId}} MUST only be associated explicitly with that particular pointing device for the lifetime of the page / session, and a new randomized {{pointerId}} MUST be chosen the next time that particular pointing device is used again in a new session.

The {{pointerId}} selection algorithm is implementation specific. Authors cannot assume values convey any particular meaning other than an identifier for the pointer that is unique from all other active pointers. As an example, user agents may simply assign a number, starting from0, to any active pointers, in the order that they become active — but these values are not guaranteed to be monotonically increasing. As the reuse of the same {{pointerId}} for a particular pointing device is left up to individual implementations, authors are strongly discouraged from relying on it, and to refer to {{persistentDeviceId}} instead.

width

The width (magnitude on the X axis), in CSS pixels (see [[CSS21]]), of thecontact geometry of the pointer. This value MAY be updated on each event for a given pointer. For inputs that typically lack contact geometry (such as a traditional mouse), and in cases where the actual geometry of the input is not detected by the hardware, theuser agent MUST return a default value of1.

height

The height (magnitude on the Y axis), in CSS pixels (see [[CSS21]]), of thecontact geometry of the pointer. This value MAY be updated on each event for a given pointer. For inputs that typically lack contact geometry (such as a traditional mouse), and in cases where the actual geometry of the input is not detected by the hardware, theuser agent MUST return a default value of1.

pressure

The normalized pressure of the pointer input in the range of[0,1], where0 and1 represent the minimum and maximum pressure the hardware is capable of detecting, respectively. For hardware and platforms that do not support pressure, the value MUST be0.5 when in theactive buttons state and0 otherwise.

tangentialPressure

The normalized tangential pressure (also known as barrel pressure), typically set by an additional control (e.g. a finger wheel on an airbrush stylus), of the pointer input in the range of[-1,1], where0 is the neutral position of the control. Note that some hardware may only support positive values in the range of[0,1]. For hardware and platforms that do not support tangential pressure, the value MUST be0.

Despite the property's name, in practice the hardware controls/sensors that generate the values for this property may not necessarily be pressure sensitive. As an example, in most cases the finger wheel on most airbrush/painting stylus implementations can be freely set, rather than requiring the user to apply a constant pressure on the wheel to prevent it from returning to the zero position.

tiltX

The plane angle (in degrees, in the range of[-90,90]) between the Y-Z plane and the plane containing both the transducer (e.g. pen/stylus) axis and the Y axis. A positivetiltX is to the right, in the direction of increasing X values.tiltX can be used along withtiltY to represent the tilt away from the normal of a transducer with the digitizer. For hardware and platforms that do not report tilt or angle, the value MUST be0.

tiltY

The plane angle (in degrees, in the range of[-90,90]) between the X-Z plane and the plane containing both the transducer (e.g. pen/stylus) axis and the X axis. A positivetiltY is towards the user, in the direction of increasing Y values.tiltY can be used along withtiltX to represent the tilt away from the normal of a transducer with the digitizer. For hardware and platforms that do not report tilt or angle, the value MUST be0.

twist

The clockwise rotation (in degrees, in the range of[0,359]) of a transducer (e.g. pen/stylus) around its own major axis. For hardware and platforms that do not report twist, the value MUST be0.

altitudeAngle

The altitude (in radians) of the transducer (e.g. pen/stylus), in the range[0,π/2] — where0 is parallel to the surface (X-Y plane), andπ/2 is perpendicular to the surface. For hardware and platforms that do not report tilt or angle, the value MUST beπ/2.

The default value defined here foraltitudeAngle isπ/2, which positions the transducer as being perpendicular to the surface. This differs from theTouch Events - Level 2 specification's definition for thealtitudeAngle property, which has a default value of0.

altitudeAngle explanation diagram — Example`altitudeAngle` of`π/4` (45 degrees from the X-Y plane).

azimuthAngle

The azimuth angle (in radians) of the transducer (e.g. pen/stylus), in the range[0, 2π] — where0 represents a transducer whose cap is pointing in the direction of increasing X values (point to "3 o'clock" if looking straight down) on the X-Y plane, and the values progressively increase when going clockwise (π/2 at "6 o'clock",π at "9 o'clock",3π/2 at "12 o'clock"). When the transducer is perfectly perpendicular to the surface (altitudeAngle ofπ/2), the value MUST be0. For hardware and platforms that do not report tilt or angle, the value MUST be0.

pointerType

Indicates the device type that caused the event (such as mouse, pen, touch). If the user agent is tofire a pointer event for a mouse, pen/stylus, or touch input device, then the value ofpointerType MUST be according to the following table:

Pointer Device Type	`pointerType` Value
Mouse	`mouse`
Pen / stylus	`pen`
Touch contact	`touch`

If the device type cannot be detected by the user agent, then the value MUST be an empty string. If the user agent supports pointer device types other than those listed above, the value ofpointerType SHOULD be vendor prefixed to avoid conflicting names for different types of devices. Future specifications MAY provide additional normative values for other device types.

SeeExample 2 for a basic demonstration of how thepointerType can be used. Also note that developers should include some form of default handling to cover user agents that may have implemented their own custompointerType values and for situations wherepointerType is simply an empty string.

isPrimary

Indicates if the pointer represents theprimary pointer of this pointer type.

persistentDeviceId

A unique identifier for the pointing device. If the hardware supports multiple pointers, pointer events generated from pointing devices MUST only get apersistentDeviceId if those pointers are uniquely identifiable over the session. If the pointer is uniquely identifiable, the assignedpersistentDeviceId to that pointing device will remain constant for the remainder of the session. ThepersistentDeviceId value of0 MUST be reserved and used to indicate events whose generating device could not be identified. LikepointerId, to minimize the chance of fingerprinting and tracking across different pages or domains, thepersistentDeviceId MUST only be associated explicitly with that particular pointing device for the lifetime of the page / session, and a new randomizedpersistentDeviceId MUST be chosen the next time that particular pointing device is used again in a new session.

Due to digitizer and pointing device hardware constraints, apersistentDeviceId is not guaranteed to be available for all pointer events from a pointing device. For example, the device may not report its hardware id to the digitizer in time forpointerdown to have apersistentDeviceId. In such a case, thepersistentDeviceId may initially be0 and change to a valid value.

getCoalescedEvents()

A method that returns the list ofcoalesced events.

getPredictedEvents()

A method that returns the list ofpredicted events.

ThePointerEventInit dictionary is used by the {{PointerEvent}} interface's constructor to provide a mechanism by which to construct untrusted (synthetic) pointer events. It inherits from the {{MouseEventInit}} dictionary defined in [[UIEVENTS]]. See theexamples for sample code demonstrating how to fire an untrusted pointer event.

The [=event constructing steps=] forPointerEvent clones {{PointerEventInit}}'s {{PointerEventInit/coalescedEvents}} tocoalesced events list and clones {{PointerEventInit}}'s {{PointerEventInit/predictedEvents}} topredicted events list.

ThePointerEvent interface inherits from {{MouseEvent}}, defined in [[[UIEVENTS]]]. Also note the proposed extension in [[[CSSOM-VIEW]]], which changes the various coordinate properties fromlong todouble to allow for fractional coordinates. For user agents that already implement this proposed extension for {{PointerEvent}}, butnot for regular {{MouseEvent}}, there are additional requirements when it comes to theclick,auxclick, andcontextmenu events.

Button states

Chorded button interactions

Some pointer devices, such as mouse or pen, support multiple buttons. In the [[UIEVENTS]] Mouse Event model, each button press produces amousedown andmouseup event. To better abstract this hardware difference and simplify cross-device input authoring, Pointer Events do not fire overlapping {{pointerdown}} and {{pointerup}} events for chorded button presses (depressing an additional button while another button on the pointer device is already depressed).

Instead, chorded button presses can be detected by inspecting changes to thebutton andbuttons properties. Thebutton andbuttons properties are inherited from the {{MouseEvent}} interface, but with a change in semantics and values, as outlined in the following sections.

The modifications to thebutton andbuttons properties apply only to pointer events. However forclick,auxclick andcontextmenu the value ofbutton andbuttons MUST follow [[UIEVENTS]], as is the case forcompatibility mouse events .

The`button` property

To identify button state transitions in any pointer event (and not just {{pointerdown}} and {{pointerup}}), thebutton property indicates the device button whose state change fired the event.

Device Button Changes	`button`
Neither buttons nor touch/pen contact changed since last event	-1
Left Mouse, Touch contact, Pen contact	0
Middle Mouse	1
Right Mouse, Pen barrel button	2
X1 (back) Mouse	3
X2 (forward) Mouse	4
Pen eraser button	5

During a mouse drag, the value of thebutton property in a {{pointermove}} event will be different from that in amousemove event. For example, while moving the mouse with the right button pressed, the {{pointermove}} events will have thebutton value -1, but themousemove events will have thebutton value 2.

The`buttons` property

Thebuttons property gives the current state of the device buttons as a bitmask (same as inMouseEvent, but with an expanded set of possible values).

Current state of device buttons	`buttons`
Mouse moved with no buttons pressed, Pen moved while hovering with no buttons pressed	0
Left Mouse, Touch contact, Pen contact	1
Middle Mouse	4
Right Mouse, Pen barrel button	2
X1 (back) Mouse	8
X2 (forward) Mouse	16
Pen eraser button	32

Theprimary pointer

In a multi-pointer (e.g. multi-touch) scenario, theisPrimary property is used to identify a master pointer amongst the set ofactive pointers for each pointer type.

At any given time, there can only ever be at most one primary pointer for each pointer type.
The first pointer to become active for a particular pointer type (e.g. the first finger to touch the screen in a multi-touch interaction) becomes the primary pointer for that pointer type.
Only a primary pointer will producecompatibility mouse events. In the case where there are multipleprimary pointers, these pointers will all producecompatibility mouse events.

Authors who desire single-pointer interaction can achieve this by ignoring non-primary pointers (however, see the note below onmultiple primary pointers).

When two or more pointer device types are being used concurrently, multiple pointers (one for eachpointerType) are considered primary. For example, a touch contact and a mouse cursor moved simultaneously will produce pointers that are both considered primary.

Some devices, operating systems and user agents may ignore the concurrent use of more than one type of pointer input to avoid accidental interactions. For instance, devices that support both touch and pen interactions may ignore touch inputs while the pen is actively being used, to allow users to rest their hand on the touchscreen while using the pen (a feature commonly referred to as "palm rejection"). Currently, it is not possible for authors to suppress this behavior.

In some cases, it is possible for the user agent to fire pointer events in which no pointer is marked as a primary pointer. For instance, when there are multiple active pointers of a particular type, like a multi-touch interaction, and the primary pointer is removed (e.g. it leaves the screen), there may end up being no primary pointers. Also on platforms where the primary pointer is determined using all active pointers of the same type on the device (including those targeted at an application other than the user agent), if the first (primary) pointer is outside of the user agent and other (non-primary) pointers targeted inside the user agent, then theuser agent MAY fire pointer events for the other pointers with a value offalse forisPrimary.

Current operating systems and user agents don't usually have a concept of multiple mouse inputs. When more than one mouse device is present (for instance, on a laptop with both a trackpad and an external mouse), all mouse devices are generally treated as a single device — movements on any of the devices are translated to movement of a single mouse pointer, and there is no distinction between button presses on different mouse devices. For this reason, there will usually only be a single mouse pointer, and that pointer will be primary.

Firing events using the`PointerEvent` interface

Tofire a pointer event named |e| means to [=fire an event=] named |e| usingPointerEvent whose attributes are set as defined in {{PointerEvent}} Interface andAttributes and Default Actions.

If the event is not a {{gotpointercapture}}, {{lostpointercapture}},click,auxclick orcontextmenu event, run theprocess pending pointer capture steps for thisPointerEvent.

Determine the target at which the event is fired as follows:

If thepointer capture target override has been set for the pointer, set the target topointer capture target override object.
Otherwise, set the target to the object returned byhit test.

Let |targetDocument| be target's [=Node/node document=] [[DOM]].

If the event is {{pointerdown}}, {{pointermove}}, or {{pointerup}}, setactive document for the event's {{PointerEvent/pointerId}} to |targetDocument|.

If the event is {{pointerdown}}, the associated device is a direct manipulation device, and the target is an {{Element}}, thenset pointer capture for this {{PointerEvent/pointerId}} to the target element as described inimplicit pointer capture.

Before firing this event, theuser agent SHOULD treat the target as if the pointing device has moved over it from the |previousTarget| for the purpose ofensuring event ordering [[UIEVENTS]]. If the |needsOverEvent| flag is set, a {{pointerover}} event is needed even if the target element is the same.

Fire the event to the determined target.

Using thepointer capture target override as the target instead of the normal hit-test result may fire some boundary events, as defined by [[UIEVENTS]]. This is the same as the pointer leaving its previous target and entering this new capturing target. When the capture is released, the same scenario may happen, as the pointer is leaving the capturing target and entering the hit-test target.

Attributes and default actions

Thebubbles andcancelable properties and the default actions for the event types defined in this specification appear in the following table. Details of each of these event types are provided inPointer Event types.

Event Type	Bubbles	Cancelable	Default Action
{{pointerover}}	Yes	Yes	None
{{pointerenter}}	No	No	None
{{pointerdown}}	Yes	Yes	Varies: when the pointer is primary, all default actions of the`mousedown` event Canceling this event also prevents subsequent firing ofcompatibility mouse events.
{{pointermove}}	Yes	Yes	Varies: when the pointer is primary, all default actions of`mousemove`
{{pointerrawupdate}}	Yes	No	None
{{pointerup}}	Yes	Yes	Varies: when the pointer is primary, all default actions of`mouseup`
{{pointercancel}}	Yes	No	None
{{pointerout}}	Yes	Yes	None
{{pointerleave}}	No	No	None
{{gotpointercapture}}	Yes	No	None
{{lostpointercapture}}	Yes	No	None

Viewport manipulations (panning and zooming) — generally, as a result of adirect manipulation interaction — are intentionally NOT a default action of pointer events, meaning that these behaviors (e.g. panning a page as a result of moving a finger on a touchscreen) cannot be suppressed by canceling a pointer event. Authors must instead usetouch-action to explicitlydeclare the direct manipulation behavior for a region of the document. Removing this dependency on the cancelation of events facilitates performance optimizations by the user agent.

For {{pointerenter}} and {{pointerleave}} events, the {{EventInit/composed}} [[DOM]] attribute SHOULD befalse; for all other pointer events in the table above, the attribute SHOULD betrue.

For all pointer events in the table above, the {{UIEvent/detail}} [[UIEVENTS]] attribute SHOULD be 0.

Many user agents expose non-standard attributesfromElement andtoElement in MouseEvents to support legacy content. We encourage those user agents to set the values of those (inherited) attributes in PointerEvents tonull to transition authors to the use of standardized alternates (target andrelatedTarget).

Similar toMouseEvent {{MouseEventInit/relatedTarget}}, therelatedTarget should be initialized to the element whose bounds the pointer just left (in the case of a {{pointerover}} orpointerenter event) or the element whose bounds the pointer is entering (in the case of a {{pointerout}} or {{pointerleave}}). For other pointer events, this value will default to null. Note that when an element receives the pointer capture all the following events for that pointer are considered to be inside the boundary of the capturing element.

For {{gotpointercapture}} and {{lostpointercapture}} events, all the attributes except the ones defined in the table above should be the same as the Pointer Event that caused the user agent to run theprocess pending pointer capture steps and fire the {{gotpointercapture}} and {{lostpointercapture}} events.

Process pending pointer capture

Theuser agent MUST run the following steps whenimplicitly releasing pointer capture as well as when firing Pointer Events that are not {{gotpointercapture}} or {{lostpointercapture}}.

If thepointer capture target override for this pointer is set and is not equal to thepending pointer capture target override, then fire a pointer event named {{lostpointercapture}} at thepointer capture target override node.
If thepending pointer capture target override for this pointer is set and is not equal to thepointer capture target override, then fire a pointer event named {{gotpointercapture}} at thepending pointer capture target override.
Set thepointer capture target override to thepending pointer capture target override, if set. Otherwise, clear thepointer capture target override.

As defined in the section forclick,auxclick, andcontextmenu events, even after the {{lostpointercapture}} event has been dispatched, the correspondingclick,auxclick orcontextmenu event, if any, would still be dispatched to the capturing target.

Suppressing a pointer event stream

Theuser agent MUSTsuppress a pointer event stream when it detects that the web page is unlikely to continue to receive pointer events with a specific {{PointerEvent/pointerId}}. Any of the following scenarios satisfy this condition (there MAY be additional scenarios):

The user agent has opened a modal dialog or menu.
A pointer input device is physically disconnected, or a hoverable pointer input device (e.g. a hoverable pen/stylus) has left the hover range detectable by the digitizer.
The pointer is subsequently used by the user agent to manipulate the page viewport (e.g. panning or zooming). See the section ontouch-action CSS property for details.
User agents can trigger panning or zooming through multiple pointer types (such as touch and pen), and therefore the start of a pan or zoom action may result in the suppression of various pointers, including pointers with different pointer types.
As part of the drag operation initiation algorithm as defined in thedrag and drop processing model [[HTML]], for the pointer that caused the drag operation.

Other scenarios in which theuser agent MAYsuppress a pointer event stream include:

A device's screen orientation is changed while a pointer is active.
The user attempts to interact using more simultaneous pointer inputs than the device supports.
The user agent interprets the input as accidental (for example, the hardware supports palm rejection).

Methods for detecting any of these scenarios are out of scope for this specification.

Theuser agent MUST run the following steps tosuppress a pointer event stream:

Fire a {{pointercancel}} event.
Fire a {{pointerout}} event.
Fire a {{pointerleave}} event.
Implicitly release the pointer capture if the pointer is currently captured.

Boundary events caused by layout changes

A pointing device that moved relative to the screen surface or underwent some change in any of its properties fires various events as defined inPointer Event types. For a stationary pointing device (that neither moved relative to the screen surface nor underwent any change in any properties), theuser agent MUST fire certain boundary events after a layout change that affected thehit test target for the pointer, see {{pointerover}}, {{pointerenter}}, {{pointerout}} and {{pointerleave}} for details. Theuser agent MAY delay the firing of these boundary events because of performance reasons (e.g. to avoid too many hit-tests or layout changes caused by boundary event listeners).

A stationary pointing device (that neither moved relative to the screen surface nor underwent any change in any properties) never fires a {{pointermove}} event.

Converting between`tiltX` /`tiltY` and`altitudeAngle` /`azimuthAngle`

Pointer Events include two complementary sets of attributes to express the orientation of a transducer relative to the X-Y plane:tiltX /tiltY (introduced in the original Pointer Events specification), andazimuthAngle /altitudeAngle (adopted from theTouch Events - Level 2 specification).

Depending on the specific hardware and platform, user agents will likely only receive one set of values for the transducer orientation relative to the screen plane — eithertiltX /tiltY oraltitudeAngle /azimuthAngle. User agents MUST use the following algorithm for converting these values.

When the user agent calculatestiltX /tiltY fromazimuthAngle /altitudeAngle it SHOULD round the final integer values usingMath.round [[ECMASCRIPT]] rules.

/* Converting between tiltX/tiltY and altitudeAngle/azimuthAngle */function spherical2tilt(altitudeAngle, azimuthAngle) {  const radToDeg = 180/Math.PI;  let tiltXrad = 0;  let tiltYrad = 0;  if (altitudeAngle == 0) {    // the pen is in the X-Y plane    if (azimuthAngle == 0 || azimuthAngle == 2*Math.PI) {      // pen is on positive X axis      tiltXrad = Math.PI/2;    }    if (azimuthAngle == Math.PI/2) {      // pen is on positive Y axis      tiltYrad = Math.PI/2;    }    if (azimuthAngle == Math.PI) {      // pen is on negative X axis      tiltXrad = -Math.PI/2;    }    if (azimuthAngle == 3*Math.PI/2) {      // pen is on negative Y axis      tiltYrad = -Math.PI/2;    }    if (azimuthAngle>0 && azimuthAngle<Math.PI/2) {      tiltXrad = Math.PI/2;      tiltYrad = Math.PI/2;    }    if (azimuthAngle>Math.PI/2 && azimuthAngle<Math.PI) {      tiltXrad = -Math.PI/2;      tiltYrad = Math.PI/2;    }    if (azimuthAngle>Math.PI && azimuthAngle<3*Math.PI/2) {      tiltXrad = -Math.PI/2;      tiltYrad = -Math.PI/2;    }    if (azimuthAngle>3*Math.PI/2 && azimuthAngle<2*Math.PI) {      tiltXrad = Math.PI/2;      tiltYrad = -Math.PI/2;    }  }  if (altitudeAngle != 0) {    const tanAlt = Math.tan(altitudeAngle);    tiltXrad = Math.atan(Math.cos(azimuthAngle) / tanAlt);    tiltYrad = Math.atan(Math.sin(azimuthAngle) / tanAlt);  }  return {"tiltX":tiltXrad*radToDeg, "tiltY":tiltYrad*radToDeg};}function tilt2spherical(tiltX, tiltY) {  const tiltXrad = tiltX * Math.PI/180;  const tiltYrad = tiltY * Math.PI/180;  // calculate azimuth angle  let azimuthAngle = 0;  if (tiltX == 0) {    if (tiltY > 0) {      azimuthAngle = Math.PI/2;    }    else if (tiltY < 0) {      azimuthAngle = 3*Math.PI/2;    }  } else if (tiltY == 0) {    if (tiltX < 0) {      azimuthAngle = Math.PI;    }  } else if (Math.abs(tiltX) == 90 || Math.abs(tiltY) == 90) {    // not enough information to calculate azimuth    azimuthAngle = 0;  } else {    // Non-boundary case: neither tiltX nor tiltY is equal to 0 or +-90    const tanX = Math.tan(tiltXrad);    const tanY = Math.tan(tiltYrad);    azimuthAngle = Math.atan2(tanY, tanX);    if (azimuthAngle < 0) {      azimuthAngle += 2*Math.PI;    }  }  // calculate altitude angle  let altitudeAngle = 0;  if (Math.abs(tiltX) == 90 || Math.abs(tiltY) == 90) {      altitudeAngle = 0  } else if (tiltX == 0) {    altitudeAngle = Math.PI/2 - Math.abs(tiltYrad);  } else if (tiltY == 0) {    altitudeAngle = Math.PI/2 - Math.abs(tiltXrad);  } else {    // Non-boundary case: neither tiltX nor tiltY is equal to 0 or +-90    altitudeAngle =  Math.atan(1.0/Math.sqrt(Math.pow(Math.tan(tiltXrad),2) + Math.pow(Math.tan(tiltYrad),2)));  }  return {"altitudeAngle":altitudeAngle, "azimuthAngle":azimuthAngle};}

PointerEvent Algorithms

initialize a {{PointerEvent}}

[=Initialize a MouseEvent=] with |event|, |eventType| and |eventTarget|, |bubbles| and |cancelable|
Initialize all other attributes to default {{PointerEvent}} values.

create a {{PointerEvent}}

Tocreate a {{PointerEvent}} with |eventType| and |eventTarget|, |bubbles|, and |cancelable|, run the following steps:

Let |event| be the result of [=creating an event=] using {{PointerEvent}}
[=Initialize a PointerEvent=] with |event|, |eventType| and |eventTarget|, |bubbles| and |cancelable|
Return |event|

create {{PointerEvent}} from {{MouseEvent}}

Let |eventType| be a {{DOMString}} containing the event type
Let |mouseevent| be the corresponding {{MouseEvent}}
Let |event| be the result of [=creating an event=] using {{PointerEvent}}
Let |target| be the |mouseevent|.{{Event/target}}
[=Initialize a PointerEvent=] with |event|, |eventType| and |target|
Copy {{MouseEvent}} attributes from |mouseevent| into |event|
Return |event|

maybe send pointerout event

Let |mouseout| be the corresponding mouseout {{MouseEvent}}
Let |pointerout| be the result of [=creating PointerEvent from MouseEvent=] with "pointerout" and |mouseout|
Set pointerevent attributes
TODO.
Let |target| be the |mouseout|.{{Event/target}}
[=dispatch=] |pointerout| at |target|

maybe send pointerleave event

Let |mouseout| be the corresponding mouseout {{MouseEvent}}
Let |pointerout| be the result of [=creating PointerEvent from MouseEvent=] with "pointerout" and |mouseout|
Set pointerevent attributes
TODO.
Let |target| be the |mouseout|.{{Event/target}}
[=dispatch=] |pointerout| at |target|

maybe send pointerover event

Let |mouseout| be the corresponding mouseout {{MouseEvent}}
Let |pointerout| be the result of [=creating PointerEvent from MouseEvent=] with "pointerout" and |mouseout|
Set pointerevent attributes
TODO.
Let |target| be the |mouseout|.{{Event/target}}
[=dispatch=] |pointerout| at |target|

maybe send pointerenter event

Let |mouseout| be the corresponding mouseout {{MouseEvent}}
Let |pointerout| be the result of [=creating PointerEvent from MouseEvent=] with "pointerout" and |mouseout|
Set pointerevent attributes
TODO.
Let |target| be the |mouseout|.{{Event/target}}
[=dispatch=] |pointerout| at |target|

maybe send pointermove event

Let |mouseout| be the corresponding mouseout {{MouseEvent}}
Can this send pointermove and pointerrawupdate? Or do we need 2 methods?
What is needed to properly define how pointermove events are coalesced?
Let |pointerout| be the result of [=creating PointerEvent from MouseEvent=] with "pointerout" and |mouseout|
Set pointerevent attributes
TODO.
Let |target| be the |mouseout|.{{Event/target}}
[=dispatch=] |pointerout| at |target|

maybe send pointerdown event

Let |mouseout| be the corresponding mouseout {{MouseEvent}}
Unlikemousedown events, {{pointerdown}} events are not nested when multiple buttons are pressed. The {{MouseEvent}} is passed so that the fields can be copied into the PointerEvent.
Let |pointerout| be the result of [=creating PointerEvent from MouseEvent=] with "pointerout" and |mouseout|
Set pointerevent attributes
TODO.
Let |target| be the |mouseout|.{{Event/target}}
[=dispatch=] |pointerout| at |target|

maybe send pointerrawupdate event

Let |mouseout| be the corresponding mouseout {{MouseEvent}}
Let |target| be the |mouseout|.{{Event/target}}
[=dispatch=] |pointerout| at |target|

maybe send pointerup event

Let |mouseout| be the corresponding mouseout {{MouseEvent}}
Unlikemouseup events, {{pointerup}} events are not nested when multiple buttons are pressed. The {{MouseEvent}} is passed so that the fields can be copied into the PointerEvent.
Let |pointerout| be the result of [=creating PointerEvent from MouseEvent=] with "pointerout" and |mouseout|
Set pointerevent attributes
TODO.
Let |target| be the |mouseout|.{{Event/target}}
[=dispatch=] |pointerout| at |target|

Pointer Event types

Below are the event types defined in this specification.

In the case of theprimary pointer, these events (with the exception of {{gotpointercapture}} and {{lostpointercapture}}) may also firecompatibility mouse events.

Thepointerover event

Theuser agent MUSTfire a pointer event named {{pointerover}} when any of the following occurs:

The step todetermine the target of a pointer detects that the pointer has moved into an element.
Alayout change causes thehit test boundaries of an element to move underneath an uncaptured pointer of a stationary pointing device.
Before the user agent fires a {{pointerdown}} event for a device thatdoes not support hover (see {{pointerdown}}).

Thepointerenter event

Theuser agent MUSTfire a pointer event named {{pointerenter}} when any of the following occurs:

The step todetermine the target of a pointer detects that the pointer has moved into an element or one of its descendants.
Alayout change causes thehit test boundaries of an element or one of its descendants to move underneath an uncaptured pointer of a stationary pointing device.
Before the user agent fires a {{pointerdown}} event for a device thatdoes not support hover (see {{pointerdown}}).

This event type is similar to {{pointerover}} but with two differences: {{pointerenter}} does not bubble, and its dispatch considers thehit test boundaries of even descendant elements.

There are similarities between this event type, themouseenter event described in [[UIEVENTS]], and the CSS:hover pseudo-class described in [[CSS21]]. See also the {{pointerleave}} event.

Thepointerdown event

Theuser agent MUSTfire a pointer event named {{pointerdown}} when a pointer enters theactive buttons state. For mouse, this is when the device transitions from no buttons depressed to at least one button depressed. For touch, this is when physical contact is made with thedigitizer. For pen, this is when the pen either makes physical contact with the digitizer without any button depressed, or transitions from no buttons depressed to at least one button depressed while hovering.

For mouse (or other multi-button pointer devices), this means {{pointerdown}} and {{pointerup}} are not fired for all of the same circumstances asmousedown andmouseup. Seechorded buttons for more information.

For inputdevices that do not support hover, theuser agent MUST alsofire a pointer event named {{pointerover}} followed by a pointer event named {{pointerenter}} prior to dispatching the {{pointerdown}} event.

Authors can prevent the firing of certaincompatibility mouse events by canceling the {{pointerdown}} event (if theisPrimary property istrue). This sets thePREVENT MOUSE EVENT flag on the pointer. Note, however, that this does not prevent themouseover,mouseenter,mouseout, ormouseleave events from firing.

Thepointermove event

Theuser agent MUSTfire a pointer event named {{pointermove}} when a pointer changes any properties that don't fire {{pointerdown}} or {{pointerup}} events. This includes any changes to coordinates, pressure, tangential pressure, tilt, twist, contact geometry (width andheight) orchorded buttons.

User agents MAY delay dispatch of the {{pointermove}} event (for instance, for performance reasons). Thecoalesced events information will be exposed via the{{PointerEvent/getCoalescedEvents}} method for the single dispatched {{pointermove}} event. The final coordinates of such events should be used for finding the target of the event.

Thepointerrawupdate event

Theuser agent MUSTfire a pointer event named {{pointerrawupdate}}, and only do so within a [=secure context=], when a pointer changes any properties that don't firepointerdown orpointerup events. Seepointermove event for a list of such properties.

In contrast with {{pointermove}}, user agents SHOULD dispatch {{pointerrawupdate}} events as soon as possible and as frequently as the JavaScript can handle the events.

Thetarget of {{pointerrawupdate}} events might be different from the {{pointermove}} events due to the fact that {{pointermove}} events might get delayed or coalesced, and the final position of the event which is used for finding thetarget could be different from its coalesced events.

Note that if there is already another {{pointerrawupdate}} with the same {{PointerEvent/pointerId}} that hasn't been dispatched in the [=event loop=], theuser agent MAY coalesce the new {{pointerrawupdate}} with that event instead of creating a new [=task=]. This may cause {{pointerrawupdate}} to have coalesced events, and they will all be delivered ascoalesced events of one {{pointerrawupdate}} event as soon as the event is processed in the [=event loop=]. See{{PointerEvent/getCoalescedEvents}} for more information.

In terms of ordering of {{pointerrawupdate}} and {{pointermove}}, if the user agent received an update from the platform that causes both {{pointerrawupdate}} and {{pointermove}} events, then theuser agent MUST dispatch the {{pointerrawupdate}} event before the corresponding {{pointermove}}.

Other than thetarget, the concatenation of coalesced events lists of all dispatched {{pointerrawupdate}} events since the last {{pointermove}} event is the same as the coalesced events of the next {{pointermove}} event in terms of the other event attributes. The attributes of {{pointerrawupdate}} are mostly the same as {{pointermove}}, with the exception ofcancelable which MUST be false for {{pointerrawupdate}}.

User agents SHOULD not firecompatibility mouse events for {{pointerrawupdate}}.

Adding listeners for the {{pointerrawupdate}} event might negatively impact the performance of the web page, depending on the implementation of the user agent. For most use cases the other pointerevent types should suffice. A {{pointerrawupdate}} listener should only be added if JavaScript needs high frequency events and can handle them just as fast. In these cases, there is probably no need to listen to other types of pointer events.

Thepointerup event

Theuser agent MUSTfire a pointer event named {{pointerup}} when a pointer leaves theactive buttons state. For mouse, this is when the device transitions from at least one button depressed to no buttons depressed. For touch, this is when physical contact is removed from thedigitizer. For pen, this is when the pen is removed from the physical contact with the digitizer while no button is depressed, or transitions from at least one button depressed to no buttons depressed while hovering.

For inputdevices that do not support hover, theuser agent MUST alsofire a pointer event named {{pointerout}} followed by a pointer event named {{pointerleave}} after dispatching the {{pointerup}} event.

All {{pointerup}} events have apressure value of0.

Theuser agent MUST alsoimplicitly release the pointer capture if the pointer is currently captured.

Thepointercancel event

Theuser agent MUSTfire a pointer event named {{pointercancel}} when it detects a scenario tosuppress a pointer event stream.

The values of the following properties of the {{pointercancel}} event MUST match the values of the last dispatched pointer event with the same {{PointerEvent/pointerId}}:width,height,pressure,tangentialPressure,tiltX,tiltY,twist,altitudeAngle,azimuthAngle,pointerType,isPrimary, and the coordinates inherited from [[UIEVENTS]]. ThecoalescedEvents andpredictedEvents lists in the {{pointercancel}} event MUST be empty, and the event's {{Event/cancelable}} attribute MUST be false.

Thepointerout event

Theuser agent MUSTfire a pointer event named {{pointerout}} when any of the following occurs:

The step todetermine the target of a pointer detects that the pointer has moved out of an element.
Alayout change causes thehit test boundaries of an element to move away from underneath an uncaptured pointer of a stationary pointing device.
After the user agent fires a {{pointerup}} event for a device thatdoes not support hover (see {{pointerup}}).
The user agent has detected a scenario tosuppress a pointer event stream.

Thepointerleave event

Theuser agent MUSTfire a pointer event named {{pointerleave}} when any of the following occurs:

The step todetermine the target of a pointer detects that the pointer has moved out of an element and all of its descendants.
Alayout change causes thehit test boundaries of an element and all of its descendants to move away from underneath an uncaptured pointer of a stationary pointing device.
After the user agent fires the {{pointerup}} event for a device thatdoes not support hover (see {{pointerup}}).
The user agent has detected a scenario tosuppress a pointer event stream.

This event type is similar to {{pointerout}} but with two differences: {{pointerleave}} does not bubble, and its dispatch considers thehit test boundaries of even descendant elements.

There are similarities between this event type, themouseleave event described in [[UIEVENTS]], and the CSS:hover pseudo-class described in [[CSS21]]. See also the {{pointerenter}} event.

Thegotpointercapture event

Theuser agent MUSTfire a pointer event named {{gotpointercapture}} when an element receives pointer capture. This event is fired at the element that is receiving pointer capture. Subsequent events for that pointer will be fired at this element. See thesetting pointer capture andprocess pending pointer capture sections.

Thelostpointercapture event

Theuser agent MUSTfire a pointer event named {{lostpointercapture}} after pointer capture is released for a pointer. This event MUST be fired prior to any subsequent events for the pointer after capture was released. This event is fired at the element from which pointer capture was removed. All subsequent events for the pointer exceptclick,auxclick, andcontextmenu events follow normal hit testing mechanisms (out of scope for this specification) for determining the event target. See thereleasing pointer capture,implicit release of pointer capture, andprocess pending pointer capture sections.

The`click`,`auxclick`, and`contextmenu` events

This section is an addition toclick,auxclick andcontextmenu events defined in [[UIEVENTS]]. These events are typically tied to user interface activation, and are fired even from non-pointer input devices, such as keyboards.

These events MUST be of typePointerEvent, and are subject to the additional requirements mentioned in the rest of this section.

Event attributes

For these events, allPointerEvent specific attributes (defined in this spec) other than {{PointerEvent/pointerId}} andpointerType MUST have their default values. In addition:

If the events are generated by a pointing device, their {{PointerEvent/pointerId}} andpointerType MUST be the same as the PointerEvents that caused these events.
If the events are generated by a non-pointing device (such as voice recognition software or a keyboard interaction), {{PointerEvent/pointerId}} MUST be-1 andpointerType MUST be an empty string.

Event coordinates

As noted in {{PointerEvent}}, [[[CSSOM-VIEW]]] proposes to redefine the various coordinate properties (screenX,screenY,pageX,pageY,clientX,clientY,x,y,offsetX,offsetY) asdouble, to allow for fractional coordinates. However, this change — when applied only to {{PointerEvent}}, but not to regular {{MouseEvent}} — has proven to lead to web compatibility issues with legacy code in the case ofclick,auxclick, andcontextmenu. For this reason, user agents that have implemented the proposed change in [[[CSSOM-VIEW]]] only for {{PointerEvent}} MUST convert the various coordinate properties for theclick,auxclick, andcontextmenu tolong values (as defined in the original [[[UIEVENTS]]]) usingMath.floor [[ECMASCRIPT]].

Event dispatch

Aclick,auxclick orcontextmenu event MUST follow the dispatch process defined in the [[UIEVENTS]] spec except that the event target is overridden using the algorithm below:

Let |event| be theclick,auxclick orcontextmenu event being dispatched, and |userEvent| be the user interaction event that caused the firing of |event|.
Event |userEvent| could be a non-PointerEvent; for example, it is aKeyboardEvent when aclick event dispatch is caused by hitting the spacebar on a checkbox element.
When |userEvent| is aPointerEvent, |userEvent| is a {{pointerup}} for aclick orauxclick event, and either a {{pointerdown}} or a {{pointerup}} event (depending on native platform convention) for acontextmenu event.
If |userEvent| is not aPointerEvent, dispatch |event| following the [[UIEVENTS]] spec without overriding |event| target and skip the remaining steps below.
Define |target| as follows:
If |event| is acontextmenu event, or |userEvent| was dispatched while the corresponding pointer was captured, then let |target| be the target of |userEvent|.
Otherwise (|event| is aclick orauxclick event for which |userEvent| is apointerup event that was dispatched uncaptured) let |target| be the nearest common inclusive ancestor of the correspondingpointerdown andpointerup targets in the DOM at the moment |event| is being dispatched.
Dispatch |event| to |target| following the [[UIEVENTS]] spec.
If |userEvent| was captured, |event| is dispatched to the capturing target of |userEvent| even though the {{lostpointercapture}} event with the same {{PointerEvent/pointerId}} has been dispatched already.

Wheel Events

Wheels are devices that can be rotated in one or more spatial dimensions, and which can be associated with a pointer device. The coordinate system depends on theenvironment configuration.

The user's environment might be configured to associate vertical scrollingwith rotation along the y-axis, horizontal scrolling with rotation along thex-axis, and zooming with rotation along the z-axis.

The deltaX, deltaY, and deltaZ attributes of {{WheelEvent}} objects indicatea measurement along their respective axes in units of pixels, lines, orpages. The reported measurements are provided after an environment-specificalgorithm translates the actual rotation/movement of the wheel device intothe appropriate values and units.

A user's environment settings can be customized to interpret actual rotation/movementof a wheel device in different ways.One movement of a commondented mouse wheel can produce a measurement of 162 pixels(162 is just an example value, actual values can depend on the current screendimensions of the user-agent).But a user can change their default environment settings to speed-up their mouse wheel,increasing this number.Furthermore, some mouse wheel software can support acceleration (the faster the wheelis rotated/moved, the greater thedelta of each measurement) or even sub-pixelrotationmeasurements.Because of this, authors can not assume a givenrotation amount in one user agent willproduce the samedelta value in all user agents.

The sign (positive or negative) of the values of the deltaX, deltaY, and deltaZ attributesMUST be consistent between multiple dispatches of the{{wheel}} event while themotion of the actual wheel device is rotating/moving in the same direction.If a user agent scrolls as the default action of the{{wheel}} event then the signof thedelta SHOULD be given by a right-hand coordinate system where positive X,Y, and Z axes are directed towards the right-most edge, bottom-most edge, and farthestdepth (away from the user) of the document, respectively.

Individual user agents can (depending on their environment and hardware configuration)interpret the same physical user interaction on the wheel differently.For example, a vertical swipe on the edge of a trackpad from top to bottom can beinterpreted as a wheel action intended to either scroll thepage down or to pan the page up (i.e., resulting in either a positive or negativedeltaY value respectively).

Auser agent MUST create awheel event transaction when the first wheel eventis fired, so that all subsequent wheel events within a implementation-specific amount oftime can be targetted at the same element. Awheel event transaction is series ofwheel events that are associated with a single user gesture. Thewheel event transaction MUST have an associated event target that is thetopmost event target at the time the first wheel event occurs in the group.

If a series of wheel events targetted in a scrollable element start above a child element,later events for the same user gesture may occur over the child element.

Interface WheelEvent

The {{WheelEvent}} interface provides specific contextual informationassociated with {{wheel}} events.To create an instance of the {{WheelEvent}} interface, use the {{WheelEvent}} constructor,passing an optional {{WheelEventInit}} dictionary.

WheelEvent

[Exposed=Window]interface WheelEvent : MouseEvent {constructor(DOMString type, optional WheelEventInit eventInitDict = {});// DeltaModeCodeconst unsigned long DOM_DELTA_PIXEL = 0x00;const unsigned long DOM_DELTA_LINE= 0x01;const unsigned long DOM_DELTA_PAGE= 0x02;readonly attribute double deltaX;readonly attribute double deltaY;readonly attribute double deltaZ;readonly attribute unsigned long deltaMode;};

DOM_DELTA_PIXEL: The units of measurement for thedelta MUST be pixels.This is the most typical case in most operating system andimplementation configurations.
DOM_DELTA_LINE: The units of measurement for thedelta MUST be individuallines of text. This is the case for many form controls.
DOM_DELTA_PAGE: The units of measurement for thedelta MUST be pages,either defined as a single screen or as a demarcated page.
deltaX: In user agents where the default action of the {{wheel}}event is to scroll, the value MUST be the measurement along thex-axis (in pixels, lines, or pages) to be scrolled in the casewhere the event is not cancelled. Otherwise, this is animplementation-specific measurement (in pixels, lines, or pages)of the movement of a wheel device around the x-axis.Theun-initialized value of this attribute MUST be0.0.
deltaY: In user agents where the default action of the {{wheel}}event is to scroll, the value MUST be the measurement along they-axis (in pixels, lines, or pages) to be scrolled in the casewhere the event is not cancelled. Otherwise, this is animplementation-specific measurement (in pixels, lines, or pages)of the movement of a wheel device around the y-axis.Theun-initialized value of this attribute MUST be0.0.
deltaZ: In user agents where the default action of the {{wheel}}event is to scroll, the value MUST be the measurement along thez-axis (in pixels, lines, or pages) to be scrolled in the casewhere the event is not cancelled. Otherwise, this is animplementation-specific measurement (in pixels, lines, or pages)of the movement of a wheel device around the z-axis.Theun-initialized value of this attribute MUST be0.0.
deltaMode: ThedeltaMode attribute contains an indication ofthe units of measurement for thedelta values. Thedefault value is {{WheelEvent/DOM_DELTA_PIXEL}} (pixels).This attribute MUST be set to one of the DOM_DELTA constants toindicate the units of measurement for thedelta values.The precise measurement is specific to device, operating system,and application configurations.Theun-initialized value of this attribute MUST be0.

WheelEventInit

dictionary WheelEventInit : MouseEventInit {double deltaX = 0.0;double deltaY = 0.0;double deltaZ = 0.0;unsigned long deltaMode = 0;};

deltaX: SeedeltaZ attribute.
deltaY: SeedeltaZ attribute.
deltaZ: Initializes the {{WheelEvent/deltaZ}} attribute of the {{WheelEvent}}object. Relative positive values for this attribute (as well asthe {{WheelEvent/deltaX}} and {{WheelEvent/deltaY}} attributes) aregiven by a right-hand coordinate system where the X, Y, and Zaxes are directed towards the right-most edge, bottom-most edge,and farthest depth (away from the user) of the document,respectively. Negative relative values are in the respectiveopposite directions.
deltaMode: Initializes the {{WheelEvent/deltaMode}} attribute on the{{WheelEvent}} object to the enumerated values 0, 1, or 2, whichrepresent the amount of pixels scrolled({{WheelEvent/DOM_DELTA_PIXEL}}), lines scrolled({{WheelEvent/DOM_DELTA_LINE}}), or pages scrolled({{WheelEvent/DOM_DELTA_PAGE}}) if therotation of thewheel would have resulted in scrolling.

Wheel Event Types

wheel

Type	`wheel`
Interface	{{WheelEvent}}
Sync / Async	Async
Bubbles	Yes
Trusted Targets	`Element`
Cancelable	Varies
Composed	Yes
Default action	Scroll (or zoom) the document
Context (trusted events)	{{Event}}.{{Event/target}} : element target for the currentwheel event transaction {{UIEvent}}.{{UIEvent/view}} : {{Window}} {{UIEvent}}.{{UIEvent/detail}} :`0` {{MouseEvent}}.{{MouseEvent/screenX}} : if the wheel is associated with a pointing device, the value based on the pointer position on the screen, otherwise`0` {{MouseEvent}}.{{MouseEvent/screenY}} : if the wheel is associated with a pointing device, the value based on the pointer position on the screen, otherwise`0` {{MouseEvent}}.{{MouseEvent/clientX}} : if the wheel is associated with a pointing device, the value based on the pointer position within the viewport, otherwise`0` {{MouseEvent}}.{{MouseEvent/clientY}} : if the wheel is associated with a pointing device, the value based on the pointer position within the viewport, otherwise`0` {{MouseEvent}}.{{MouseEvent/altKey}} :`true` if`Alt` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/ctrlKey}} :`true` if`Control` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/shiftKey}} :`true` if`Shift` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/metaKey}} :`true` if`Meta` modifier was active, otherwise`false` {{MouseEvent}}.{{MouseEvent/button}} : if wheel is associated with a pointing device, value based on current button pressed, otherwise`0` {{MouseEvent}}.{{MouseEvent/buttons}} : if wheel is associated with a pointing device, value based on all buttons current depressed,`0` if no buttons pressed {{MouseEvent}}.{{MouseEvent/relatedTarget}} : indicates the [=Event/target=] the pointing device is pointing at, if any {{WheelEvent}}.{{WheelEvent/deltaX}} : expected amount that the page will scroll along the x-axis according to the deltaMode units; or an implementation-specific value of movement of a wheel around the x-axis {{WheelEvent}}.{{WheelEvent/deltaY}} : expected amount that the page will scroll along the y-axis according to the deltaMode units; or an implementation-specific value of movement of a wheel around the y-axis {{WheelEvent}}.{{WheelEvent/deltaZ}} : expected amount that the page will scroll along the z-axis according to the deltaMode units; or an implementation-specific value of movement of a wheel around the z-axis {{WheelEvent}}.{{WheelEvent/deltaMode}} : unit indicator (pixels, lines, or pages) for the deltaX, deltaY, and deltaZ attributes

Auser agent MUST dispatch this event when a mouse wheel hasbeen rotated around any axis, or when an equivalent input device(such as a mouse-ball, certain tablets or touchpads, etc.) hasemulated such an action. Depending on the platform and input device,diagonal wheeldeltas MAY be delivered either as a single{{wheel}} event with multiple non-zero axes or as separate{{wheel}} events for each non-zero axis.The typicaldefault action of the {{wheel}} event type isto scroll (or in some cases, zoom) the document by the indicatedamount. If this event is canceled, the implementation MUST NOTscroll or zoom the document (or perform whatever otherimplementation-specific default action is associated with this eventtype).

In someuser agents, or with some input devices, the speedthat the wheel has been turned can affect thedelta values,with a faster speed producing a higherdelta value.

cancelability of wheel events

CallingpreventDefault on a wheel event can preventor otherwise interrupt scrolling. For maximum scroll performance, auser agent may not wait for each wheel event associated with the scrollto be processed to see if it will be canceled. In such cases the useragent should generatewheel events whosecancelable property isfalse, indicating thatpreventDefault cannot be used to prevent or interruptscrolling. Otherwisecancelable will betrue.

In particular, a user agent should generate only uncancelablewheel events when itobservesthat there are no non-passive listeners for the event.

Declaring direct manipulation behavior

As noted inAttributes and Default Actions, viewport manipulations (panning and zooming) cannot be suppressed by canceling a pointer event. Instead, authors must declaratively define which of these behaviors they want to allow, and which they want to suppress, using thetouch-action CSS property.

While the issue of pointers used to manipulate the viewport is generally limited to touch input (where a user's finger can both interact with content and pan/zoom the page), certain user agents may also allow the same types of (direct or indirect) manipulation for other pointer types. For instance, on mobile/tablet devices, users may also be able to scroll using a stylus. While, for historical reasons, thetouch-action CSS property defined in this specification appears to refer only to touch inputs, it does in fact apply to all forms of pointer inputs that allowdirect manipulation for panning and zooming.

The`touch-action` CSS property

Name:	`touch-action`
Value:	`auto` \|`none` \| [ [`pan-x` \|`pan-left` \|`pan-right` ] \|\| [`pan-y` \|`pan-up` \|`pan-down` ] ] \|`manipulation`
Initial:	`auto`
Applies to:	all elements except: non-replaced inline elements, table rows, row groups, table columns, and column groups
Inherited:	no
Percentages:	N/A
Media:	visual
Computed value:	same as specified value
Canonical order:	per grammar
Animation type:	not animatable

Thetouch-action CSS property determines whetherdirect manipulation interactions (which are not limited to touch, despite the property's name) MAY trigger the user agent's panning and zooming behavior. See the section ontouch-action values.

Right before starting to pan or zoom, theuser agent MUSTsuppress a pointer event stream if all of the following conditions are true:

The user agent has determined (via methods out of scope for this specification) that a direct manipulation interaction is to be consumed for panning or zooming,
a {{pointerdown}} event has been sent for the pointer, and
a {{pointerup}} or {{pointercancel}} event (following the above mentioned {{pointerdown}}) has not yet been sent for the pointer.

Some user agents implement complex gestures for behaviors that involve a series of separate discrete gestures, but which are all treated as part of a single continuous gesture. For example, consider a "fling to scroll" gesture on a touchscreen: a user starts panning the document with a rapid finger movement, lifts the finger from the touchscreen, and the document continues panning with simulated inertia. While the document is still moving, the user may place their finger on the touchscreen and execute another "fling" to provide further momentum for the panning, or counteract the current panning to slow it down, stop panning altogether, or reverse the direction of the panning. As this specification does not normatively define how gestures and behaviors are implemented, it is left up to the user agent to decide whether or not the second touch (before it is interpreted as a second "fling" or counteraction of the current panning) fires pointer events or not.

touch-action does not apply/cascade through to embedded browsing contexts. For instance, even applyingtouch-action to an<iframe> won't have any effect on the behavior of direct manipulation interactions for panning and zooming within the<iframe> itself.

Determining supported direct manipulation behavior

When a user interacts with an element using adirect manipulation pointer (such as touch or stylus on a touchscreen), the effect of that input is determined by the value of thetouch-action property, and the default direct manipulation behaviors of the element and its ancestors, as follows:

A direct manipulation interaction for panning and zoomingconforms to an element'stouch-action if the behavior is allowed in the coordinate space of the element. Note that if CSS transforms have been applied, the element's coordinate space may differ from the screen coordinate in a way that affects the conformity here; for example, the X axis of an element rotated by 90 degrees with respect to the screen will be parallel to the Y-axis of the screen coordinate.
A direct manipulation interaction for panning is supported if itconforms to thetouch-action property of each element between the hit tested element and its nearest inclusive ancestor that is a [=scroll container=] (as defined in [[CSS-OVERFLOW-3]]).
A direct manipulation interaction for zooming is supported if itconforms to thetouch-action property of each element between the hit tested element and thedocument element of the [=top-level browsing context=] (as defined in [[HTML]]).
Once panning or zooming has been started, and the user agent has already determined whether or not the gesture should be handled as a user agent direct manipulation behavior, any changes to the relevanttouch-action value will be ignored for the duration of the action. For instance, programmatically changing thetouch-action value for an element fromauto tonone as part of a {{pointerdown}} handler script will not result in the user agent aborting or suppressing any of the pan or zoom behavior for that input for as long as that pointer is active.
Similarly, in the case of the varioustouch-action values ofpan-*, once the user agent has determined whether to handle a gesture directly or not at the start of the gesture, a subsequent change in the direction of the same gesture SHOULD be ignored by the user agent for as long as that pointer is active. For instance, if an element has been set totouch-action: pan-y (meaning that only vertical panning is handled by the user agent), and a touch gesture starts off horizontally, no vertical panning should occur if the user changes the direction of their gesture to be vertical while their finger is still touching the screen.

Some user agents support panning and zooming interactions involving multiple concurrent pointers (e.g. multi-touch). Methods for processing or associating thetouch-action values of multiple concurrent pointers is out of scope for this specification.

Details of`touch-action` values

Thetouch-action property covers direct manipulation behaviors related to viewport panning and zooming. Any additional user agent behaviors, such as text selection/highlighting, or activating links and form controls, MUST NOT be affected by this CSS property.

The terms "panning" and "scrolling" are considered synonymous (or, more aptly, "panning" is "scrolling" using a direct manipulation input). Defining an interaction or gesture for triggering panning/scrolling, or for triggering behavior for theauto ornone values, are out of scope for this specification.

auto: Theuser agent MAY consider any permitted direct manipulation behaviors related to panning and zooming of the viewport that begin on the element.
none: Direct manipulation interactions that begin on the element MUST NOT trigger behaviors related to viewport panning and zooming.
pan-x pan-left pan-right pan-y pan-up pan-down: Theuser agent MAY consider direct manipulation interactions that begin on the element only for the purposes of panning that starts in any of the directions specified by all of the listed values. Once panning has started, the direction may be reversed by the user even if panning that starts in the reversed direction is disallowed. In contrast, when panning is restricted to a single axis (for instance, withpan-x orpan-y), the axis cannot be changed during panning.
manipulation: Theuser agent MAY consider direct manipulation interactions that begin on the element only for the purposes of panning andcontinuous zooming (such as pinch-zoom), but MUST NOT trigger other related behaviors that rely on multiple activations that must happen within a set period of time (such as double-tap to zoom, or double-tap and hold for single-finger zoom).

Additionaltouch-action values common in implementations are defined in [[COMPAT]].

Thetouch-action property only applies to elements that support both the CSSwidth andheight properties (see [[CSS21]]). This restriction is designed to facilitate user agent optimizations forlow-latencydirect manipulation panning and zooming. For elements not supported by default, such as<span> which is anon-replaced inline element, authors can set thedisplay CSS property to a value, such asblock, that supportswidth andheight. Future specifications could extend this API to all elements.

The direction-specific pan values are useful for customizing some overscroll behaviors. For example, to implement a simple pull-to-refresh effect the document'stouch-action can be set topan-x pan-down whenever the scroll position is0 andpan-x pan-y otherwise. This allows pointer event handlers to define the behavior for upward panning/scrolling that start from the top of the document.

The direction-specific pan values can also be used for composing a component that implements custom panning with pointer event handling within an element that scrolls natively (or vice-versa). For example, an image carousel may usepan-y to ensure it receives pointer events for any horizontal pan operations without interfering with vertical panning of the document. When the carousel reaches its right-most extent, it may change itstouch-action topan-y pan-right so that a subsequent scroll operation beyond its extent can scroll the document within the viewport if possible. It's not possible to change the behavior of a panning/scrolling operation while it is taking place.

Disabling some default direct manipulation behaviors for panning and zooming may allow user agents to respond to other behaviors more quickly. For example, withauto user agents typically add 300ms of delay beforeclick to allow for double-tap gestures to be handled. In these cases, explicitly settingtouch-action: none ortouch-action: manipulation will remove this delay. Note that the methods for determining a tap or double-tap gesture are out of scope for this specification.

<div style="touch-action: none;">    This element receives pointer events for all direct manipulation interactions that otherwise lead to panning or zooming.</div>

<div style="touch-action: pan-x;">    This element receives pointer events when not panning in the horizontal direction.</div>

<div style="overflow: auto;">    <div style="touch-action: none;">        This element receives pointer events for all direct manipulation interactions that otherwise lead to panning or zooming.    </div>    <div>        Direct manipulation interactions on this element MAY be consumed for manipulating the parent.    </div></div>

<div style="overflow: auto;">    <div style="touch-action: pan-y;">        <div style="touch-action: pan-x;">            This element receives pointer events for all direct manipulation interactions because            it allows only horizontal panning yet an intermediate ancestor            (between it and the scrollable element) only allows vertical panning.            Therefore, no direct manipulation behaviors for panning/zooming are            handled by the user agent.        </div>    </div></div>

<div style="overflow: auto;">    <div style="touch-action: pan-y pan-left;">        <div style="touch-action: pan-x;">            This element receives pointer events when not panning to the left.        </div>    </div></div>

Actual events	Dispatched events
pointer ({{PointerEvent/pointerId}}=2) coordinate change	{{pointerrawupdate}} ({{PointerEvent/pointerId}}=2) w/ one coalesced event
pointer ({{PointerEvent/pointerId}}=1) coordinate change	{{pointerrawupdate}} ({{PointerEvent/pointerId}}=1) w/ one coalesced event
pointer ({{PointerEvent/pointerId}}=2) coordinate change	{{pointerrawupdate}} ({{PointerEvent/pointerId}}=2) w/ one coalesced event
pointer ({{PointerEvent/pointerId}}=2) coordinate change	{{pointerrawupdate}} ({{PointerEvent/pointerId}}=2) w/ one coalesced event
pointer ({{PointerEvent/pointerId}}=1) coordinate change	{{pointerrawupdate}} ({{PointerEvent/pointerId}}=1) w/ one coalesced event
pointer ({{PointerEvent/pointerId}}=2) coordinate change	{{pointerrawupdate}} ({{PointerEvent/pointerId}}=2) w/ one coalesced event
pointer ({{PointerEvent/pointerId}}=1) button press	{{pointermove}} ({{PointerEvent/pointerId}}=1) w/ two coalesced events {{pointermove}} ({{PointerEvent/pointerId}}=2) w/ four coalesced events {{pointerdown}} ({{PointerEvent/pointerId}}=1) w/ zero coalesced events
pointer ({{PointerEvent/pointerId}}=2) coordinate change	{{pointerrawupdate}} ({{PointerEvent/pointerId}}=2) w/ one coalesced event
pointer ({{PointerEvent/pointerId}}=2) coordinate change	{{pointerrawupdate}} ({{PointerEvent/pointerId}}=2) w/ one coalesced event
pointer ({{PointerEvent/pointerId}}=1) button release	{{pointermove}} ({{PointerEvent/pointerId}}=2) w/ two coalesced events {{pointerup}} ({{PointerEvent/pointerId}}=1) w/ zero coalesced events

Compatibility mapping with mouse events

The vast majority of web content existing today codes only to Mouse Events. The following describes an algorithm for how theuser agent MAY map generic pointer input to mouse events for compatibility with this content.

The compatibility mapping with mouse events is an OPTIONAL feature of this specification. User agents are encouraged to support the feature for best compatibility with existing legacy content.

At a high level, compatibility mouse events are intended to be "interleaved" with their respective pointer events. However, this specific order is not mandatory, and user agents that implement compatibility mouse events MAY decide to delay or group the dispatch of mouse events, as long as their relative order is consistent.

Particularly in the case of touchscreen inputs, user agents MAY apply additional heuristics for gesture recognition (unless explicitly suppressed by authors throughtouch-action). During a sequence of events between a {{pointerdown}} event and a {{pointerup}} event, the gesture recognition may have to wait until the {{pointerup}} event to detect or ignore a gesture. As a result the compatibility mouse events for the whole sequence may be dispatched together after the last {{pointerup}} event, if the user agent determined that an interaction was not intended as a particular gesture. These specifics of user agent gesture recognition are not defined in this specification, and they may differ between implementations.

Regardless of their support for compatibility mouse events, the user agents MUST always support theclick,auxclick andcontextmenu events because these events are of typePointerEvent and are therefore notcompatibility mouse events. CallingpreventDefault during a pointer event MUST NOT have an effect on whetherclick,auxclick, orcontextmenu are fired or not.

The relative order of some of these high-level events (such ascontextmenu, [=HTMLElement/focus=], [=HTMLElement/blur=]) with pointer events is undefined and varies between user agents. For example, in some user agentscontextmenu will often follow a {{pointerup}}, while in others it'll often precede a {{pointerup}} or {{pointercancel}}, and in some situations it may be fired without any corresponding pointer event (for instance, as a result of a keyboard interaction).

In addition, user agents may apply their own heuristics to determine whether or not aclick,auxclick, orcontextmenu event should be fired. Some user agents may choose not to fire these events if there are other (non-primary) pointers of the same type, or other primary pointers of a different type. User agents may determine that a particular action was not a "clean" tap, click, or long-press (for instance, if an interaction with a finger on a touch screen includes too much movement while the finger is in contact with the screen) and decide not to fire aclick,auxclick, orcontextmenu event. These aspects of user agent behavior are not defined in this specification, and they may differ between implementations.

Unless otherwise noted, the target of any mapped mouse event SHOULD be the same target as the respective pointer event unless the target is no longer participating in itsownerDocument's tree. In this case, the mouse event should be fired at the original target's nearest ancestor node (at the time it was removed from the tree) that still participates in itsownerDocument's tree, meaning that a new event path (based on the new target node) is built for the mouse event.

Authors can prevent the production of certain compatibility mouse events by canceling the {{pointerdown}} event.

Mouse events can only be prevented when the pointer is down. Hovering pointers (e.g. a mouse with no buttons pressed) cannot have their mouse events prevented.

Themouseover,mouseout,mouseenter, andmouseleave events are never prevented (even if the pointer is down).

Compatibility mouse events can't be prevented when a pointer event {{EventListener}} is set to be {{AddEventListenerOptions/passive}} [[DOM]].

Tracking the effective position of the legacy mouse pointer

While onlyprimary pointers can produce compatibility mouse events,multiple primary pointers can be active simultaneously, each producing its own compatibility mouse events. For compatibility with scripts relying on MouseEvents, the mouse transition events (mouseover,mouseout,mouseenter andmouseleave) SHOULD simulate the movement of asingle legacy mouse input. This means that the entry/exit state for every event target is valid, in accordance with [[UIEVENTS]]. User agents SHOULD guarantee this by maintaining theeffective position of the legacy mouse pointer in the document as follows.

Right before firing a {{pointerdown}}, {{pointerup}} or {{pointermove}} event, or a {{pointerleave}} event at thewindow, the user agent SHOULD run the following steps:

Let |T| be the target of the {{pointerdown}}, {{pointerup}} or {{pointermove}} event being dispatched. For the {{pointerleave}} event, unset |T|.
If |T| and currenteffective legacy mouse pointer position are both unset or they are equal, terminate these steps.
Dispatchmouseover,mouseout,mouseenter andmouseleave events as per [[UIEVENTS]] for a mouse moving from the currenteffective legacy mouse pointer position to |T|. Consider an unset value of either currenteffective legacy mouse pointer position or |T| as an out-of-window mouse position.
Seteffective legacy mouse pointer position to |T|.

Theeffective position of the legacy mouse pointer models the fact that we cannot always have a direct mapping from pointer transition events (pointerover,pointerout,pointerenter andpointerleave) to corresponding legacy mouse transition events (mouseover,mouseout,mouseenter andmouseleave). The following animation illustrates a case where a user agent needs to dispatch more legacy mouse transition events than pointer transition events to be able to reconcile two primary pointers using a single legacy mouse input.

Simultaneous mouse pointer (white cursor) and touch pointer (white "hand" cursor) causing the single legacy mouse input (orange cursor) to move between the two pointers.

In this animation, note the time period between the mouse click and the touch tap. Button 1 receives nopointerout event (because the "real" mouse pointer didn't leave the button rectangle within this period), but Button 1 receives amouseout event when theeffective position of the legacy mouse pointer moves to Button 2 on touch tap. Similarly, in the time period between the touch tap and the moment before the mouse leaves Button 1, Button 1 receives nopointerover event for the same reason, but Button 1 receives amouseover event when theeffective position of the legacy mouse pointer moves back inside Button 1.

Mapping for devices that support hover

Whenever the user agent is to dispatch a pointer event for a device that supports hover, it SHOULD run the following steps:

If theisPrimary property for the pointer event to be dispatched isfalse then dispatch the pointer event and terminate these steps.
If the pointer event to be dispatched is a {{pointerdown}}, {{pointerup}} or {{pointermove}} event, or a {{pointerleave}} event at thewindow, dispatch compatibility mouse transition events as described inTracking the effective position of the legacy mouse pointer.
Dispatch the pointer event.
If the pointer event dispatched was {{pointerdown}} and event's [=Event/canceled flag=] is set, then set thePREVENT MOUSE EVENT flag for thispointerType.
If thePREVENT MOUSE EVENT flag isnot set for thispointerType and the pointer event dispatched was:
- {{pointerdown}}, then fire amousedown event.
- {{pointermove}}, then fire amousemove event.
- {{pointerup}}, then fire amouseup event.
- {{pointercancel}}, then fire amouseup event at thewindow.
If the pointer event dispatched was {{pointerup}} or {{pointercancel}}, clear thePREVENT MOUSE EVENT flag for thispointerType.

Mapping for devices that do not support hover

Some devices, such as most touchscreens, do not support hovering a coordinate (or set of coordinates) while not in the active state. Much existing content coded to mouse events assumes that a mouse is producing the events and thus certain qualities are generally true:

The input can hover independently of activation (e.g. moving a mouse cursor without any buttons pressed).
The input will likely produce themousemove event on an element before clicking it.

Hover is sometimes used to toggle the visibility of UI elements in content designed for mouse (e.g. "hover menus"). This content is often incompatible withdevices that do not support hover. This specification does not define a mapping or behavior for compatibility with this scenario. It will be considered in a future version of the specification.

This requires that user agents provide a different mapping for these types of input devices. Whenever the user agent is to dispatch a pointer event for a device thatdoes not support hover, it SHOULD run the following steps:

If theisPrimary property for the pointer event to be dispatched isfalse then dispatch the pointer event and terminate these steps.
If the pointer event to be dispatched is {{pointerover}} and the {{pointerdown}} event has not yet been dispatched for this pointer, then fire amousemove event (for compatibility with legacy mouse-specific code).
If the pointer event to be dispatched is a {{pointerdown}}, {{pointerup}} or {{pointermove}} event, or a {{pointerleave}} event at thewindow, dispatch compatibility mouse transition events as described inTracking the effective position of the legacy mouse pointer.
Dispatch the pointer event.
If the pointer event dispatched was {{pointerdown}} and event's [=Event/canceled flag=] is set, then set thePREVENT MOUSE EVENT flag for thispointerType.
If thePREVENT MOUSE EVENT flag isnot set for thispointerType and the pointer event dispatched was:
- {{pointerdown}}, then fire amousedown event.
- {{pointermove}}, then fire amousemove event.
- {{pointerup}}, then fire amouseup event.
- {{pointercancel}}, then fire amouseup event at thewindow.
If the pointer event dispatched was {{pointerup}} or {{pointercancel}}, clear thePREVENT MOUSE EVENT flag for thispointerType.

If the user agent supports both Touch Events (as defined in [[TOUCH-EVENTS]]) and Pointer Events, theuser agent MUST NOT generateboth the compatibility mouse events as described in this section, and thefallback mouse events outlined in [[TOUCH-EVENTS]].

The activation of an element (click) with a primary pointer thatdoes not support hover (e.g. single finger on a touchscreen) would typically produce the following event sequence:

mousemove
{{pointerover}}
pointerenter
mouseover
mouseenter
{{pointerdown}}
mousedown
Zero or more {{pointermove}} andmousemove events, depending on movement of the pointer
{{pointerup}}
mouseup
{{pointerout}}
{{pointerleave}}
mouseout
mouseleave
click

If, however, the {{pointerdown}} event [=Event/canceled flag=] is set during this interaction then the sequence of events would be:

mousemove
{{pointerover}}
pointerenter
mouseover
mouseenter
{{pointerdown}}
Zero or more {{pointermove}} events, depending on movement of the pointer
{{pointerup}}
{{pointerout}}
{{pointerleave}}
mouseout
mouseleave
click

Movatterモバイル変換

Introduction

Examples

Mouse Events