Copyright © 2018 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
The features in this specification extend or modify those found in Pointer Events, a W3C Recommendation that describes events and related interfaces for handling hardware agnostic pointer input from devices including a mouse, pen, touchscreen, etc. For compatibility with existing mouse based content, this specification also describes a mapping to fire Mouse Events for other pointer device types.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This specification is an update to [PointerEvents] which was shipped broadly only by Microsoft Internet Explorer and Microsoft Edge (though a further independent and mostly interoperable implementation was present in a pre-release build of Mozilla Firefox when the Pointer Events specification was published as a W3C Recommendation). Level 2 includes editorial clarifications, new features and minor breaking changes that address certain limitations and concerns that have been raised about aspects of the design, in an effort to enable wider browser adoption.
This document was published by the Pointer Events Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation. Comments regarding this document are welcome. Please send them to public-pointer-events@w3.org (subscribe, archives). W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 07 June 2018.
Please see the Working Group's implementation report.
Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 February 2018 W3C Process Document.
This section is non-normative.
Today, most [HTML5] content is used with and/or designed for mouse input. Those that handle input in a custom manner typically code to [DOM-LEVEL-3-EVENTS] Mouse Events. Newer computing devices today, however, incorporate other forms of input, including touchscreens, pen input, etc. Event types have been proposed for handling each of these forms of input individually. However, that approach often incurs unnecessary duplication of logic and event handling overhead when adding support for a new input type. This often creates a compatibility problem when content is written with only one device type in mind. Additionally, for compatibility with existing mouse-based content, most user agents fire Mouse Events for all input types. This makes it ambiguous whether a Mouse Event represents an actual mouse device or is being produced from another input type for compatibility, which makes it hard to code to both device types simultaneously.
To reduce the cost of coding to multiple input types and also to help with the above described ambiguity with Mouse Events, this specifications defines a more abstract form of input, called a pointer. A pointer can be any point of contact on the screen made by a mouse cursor, pen, touch (including multi-touch), or other pointing input device. This model makes it easier to write sites and applications that work well no matter what hardware the user has. For scenarios when device-specific handling is desired, this specification also defines properties for inspecting the device type which produced the event. The primary goal is to provide a single set of events and interfaces that allow for easier authoring for cross-device pointer input while still allowing for device-specific handling only when necessary for an augmented experience.
An additional key goal is to enable multi-threaded user agents to handle default touch actions, such as scrolling, without blocking on script execution.
While this specification defines a unified event model for a variety of pointer inputs, this model does not cover other forms of input such as keyboards or keyboard-like interfaces (for instance, a screenreader or similar assistive technology running on a touchscreen-only device, which allows users sequential navigation through focusable controls and elements). While user agents might choose to also generate pointer events in response to these interfaces, this scenario is not covered in this specification.
In the first instance, authors are encouraged to provide equivalent functionality for all forms of input by responding to high-level events such as focus
, blur
and click
. However, when using low-level events (such as Pointer Events), authors are encouraged to ensure that all types of input are supported. In the case of keyboards and keyboard-like interfaces, this might require the addition of explicit keyboard event handling. See WCAG 2.0 Guideline 2.1 for further details.
The events for handling generic pointer input look a lot like those for mouse: pointerdown, pointermove, pointerup, pointerover, pointerout, etc. This facilitates easy content migration from Mouse Events to Pointer Events. Pointer Events provide all the usual properties present in Mouse Events (client coordinates, target element, button states, etc.) in addition to new properties for other forms of input: pressure, contact geometry, tilt, etc. So authors can easily code to Pointer Events to share logic between different input types where it makes sense, and customize for a particular type of input only where necessary to get the best experience.
While Pointer Events are sourced from a variety of input devices, they are not defined as being generated from some other set of device-specific events. While possible and encouraged for compatibility, this spec does not require other device-specific events be supported (e.g. mouse events, touch events, etc.). A user agent could support pointer events without supporting any other device events. For compatibility with content written to mouse-specific events, this specification does provide an optional section describing how to generate compatibility mouse events based on pointer input from devices other than a mouse.
This specification does not provide any advice on the expected behavior of user agents that support both Touch Events (as defined in [TOUCH-EVENTS]) and Pointer Events. For more information on the relationship between these two specifications, see the Touch Events Community Group.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, OPTIONAL, SHOULD, and SHOULD NOT are to be interpreted as described in [RFC2119].
This section is non-normative.
The following are example author code that demonstrates how the APIs in this specification might be used.
/* Bind to either Pointer Events or traditional touch/mouse */
if (window.PointerEvent) {
// if Pointer Events are supported, only listen to pointer events
target.addEventListener("pointerdown", function(e) {
// if necessary, apply separate logic based on e.pointerType
// for different touch/pen/mouse behavior
...
});
...
} else {
// traditional touch/mouse event handlers
target.addEventListener('touchstart', function(e) {
// prevent compatibility mouse events and click
e.preventDefault();
...
});
...
target.addEventListener('mousedown', ...);
...
}
// additional event listeners for keyboard handling
...
window.addEventListener("pointerdown", detectInputType);
function detectInputType(event) {
switch(event.pointerType) {
case "mouse":
/* mouse input detected */
break;
case "pen":
/* pen/stylus input detected */
break;
case "touch":
/* touch input detected */
break;
default:
/* pointerType is empty (could not be detected)
or UA-specific custom type */
}
}
<style>
/* Disable intrinsic user agent touch behaviors (such as panning or zooming) so
that all events on the canvas element are given to the application instead. */
canvas { touch-action: none; }
</style>
<canvas id="drawSurface" width="500px" height="500px" style="border:1px solid black;"></canvas>
<script>
var canvas = document.getElementById("drawSurface"),
context = canvas.getContext("2d");
if (window.PointerEvent) {
canvas.addEventListener("pointermove", paint);
if(window.navigator.maxTouchPoints>1)
// user agent and hardware support multi-touch
...
} else {
// provide fallback for user agents that do not support Pointer Events
canvas.addEventListener("mousemove", paint);
}
function paint(event) {
if(event.buttons>0)
context.fillRect(event.clientX, event.clientY, 5, 5);
}
// additional event listeners/functions for keyboard handling
...
</script>
<div style="position:absolute; top:0px; left:0px; width:100px;height:100px;"></div>
<script>
window.addEventListener("pointerdown", checkPointerSize);
function checkPointerSize(event) {
event.target.style.width = event.width + "px";
event.target.style.height = event.height + "px";
}
</script>
var event = new PointerEvent("pointerover",
{ bubbles: true,
cancelable: true,
composed: true,
pointerId: 42,
pointerType: "pen",
clientX: 300,
clientY: 500
});
eventTarget.dispatchEvent(event);
This section is non-normative.
buttons
property. For mouse, this is when the device has at least one button depressed. For touch, this is when there is physical contact with the digitizer. For pen, this is when either the pen has physical contact with the digitizer, or at least one button is depressed while hovering.pointerId
) to produce additional events within the document, then that pointer is still considered active. Examples:
preventDefault()
, returning false
in an event handler, or other means as defined by [DOM-LEVEL-3-EVENTS] and [HTML5].PointerEvent
InterfacedictionaryPointerEventInit
: MouseEventInit { long pointerId = 0; double width = 1; double height = 1; float pressure = 0; float tangentialPressure = 0; long tiltX = 0; long tiltY = 0; long twist = 0; DOMString pointerType = ""; boolean isPrimary = false; }; [Constructor(DOMString type, optionalPointerEventInit
eventInitDict), Exposed=Window] interfacePointerEvent
: MouseEvent { readonly attribute longpointerId
; readonly attribute doublewidth
; readonly attribute doubleheight
; readonly attribute floatpressure
; readonly attribute floattangentialPressure
; readonly attribute longtiltX
; readonly attribute longtiltY
; readonly attribute longtwist
; readonly attribute DOMStringpointerType
; readonly attribute booleanisPrimary
; };
pointerId
A unique identifier for the pointer causing the event. This identifier MUST be unique from all other active pointers in the top-level browsing context (as defined by [HTML5]) at the time. A user agent MAY recycle previously retired values for pointerId
from previous active pointers, if necessary.
pointerId
selection algorithm is implementation specific. Therefore 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, values are not guaranteed to be monotonically increasing.width
The width (magnitude on the X axis), in CSS pixels (see [CSS21]), of the contact 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, the user agent MUST return a default value of 1.
height
The height (magnitude on the Y axis), in CSS pixels (see [CSS21]), of the contact 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, the user agent MUST return a default value of 1.
pressure
The normalized pressure of the pointer input in the range of [0,1], where 0 and 1 represent the minimum and maximum pressure the hardware is capable of detecting, respectively. For hardware that does not support pressure, the value MUST be 0.5 when in the active buttons state and 0 otherwise. Note: all pointerup
events will have pressure 0.
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], where 0 is the neutral position of the control. Note that some hardware may only support positive values in the range of [0,1]. For hardware that does not support tangential pressure, the value MUST be 0.
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 positive tiltX
is to the right. tiltX
can be used along with tiltY
to represent the tilt away from the normal of a transducer with the digitizer. For devices that do not report tilt, the value MUST be 0.
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 positive tiltY
is towards the user. tiltY
can be used along with tiltX
to represent the tilt away from the normal of a transducer with the digitizer. For devices that do not report tilt, the value MUST be 0.
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 devices that do not report twist, the value MUST be 0.
pointerType
Indicates the device type that caused the event (mouse, pen, touch, etc.). If a user agent is to fire a pointer event for a mouse, pen stylus, or touch input device, then the value of pointerType
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 a user agent supports pointer device types other than those listed above, the value of pointerType
SHOULD be vendor prefixed to avoid conflicting names for different types of devices. Future specifications MAY provide additional normative values for other device types.
pointerType
can be used. Also note that developers should include some form of default handling to cover user agents that may have implemented their own custom pointerType
values and for situations where pointerType
is simply an empty string.isPrimary
Indicates if the pointer represents the primary pointer of this pointer type.
The PointerEventInit
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 [DOM-LEVEL-3-EVENTS]. The steps for constructing an event are defined in [DOM4]. See the examples for sample code demonstrating how to fire an untrusted pointer event.
PointerEvent
interface inherits from MouseEvent
, defined in [DOM-LEVEL-3-EVENTS] and extended by [CSSOM-VIEW].In a multi-pointer (e.g. multi-touch) scenario, the isPrimary
property is used to identify a master pointer amongst the set of active pointers for each pointer type.
pointerType
) are considered primary. For example, a touch contact and a mouse cursor moved simultaneously will produce pointers that are both considered primary.false
for isPrimary
.PointerEvent
interfaceTo fire a pointer event named e means to fire an event named e as defined in [DOM4] with an event using the PointerEvent
interface whose attributes are set as defined in PointerEvent
Interface and Attributes and Default Actions.
If the event is not gotpointercapture
or lostpointercapture
, run Process Pending Pointer Capture steps for this PointerEvent
.
The target object at which the event is fired is determined as follows:
If this is a pointerdown
event, the associated device is a direct manipulation device and the target is an Element
, then set pointer capture for this pointerId
to the target element as described in implicit pointer capture.
Fire the event to the determined target.
The bubbles
and cancelable
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 in Pointer 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 sets the PREVENT MOUSE EVENT flag for this pointerType , which prevents subsequent firing of certain compatibility mouse events. |
pointermove |
Yes | Yes | Varies: when the pointer is primary, all default actions of mousemove |
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 |
For all pointer events in the table above, composed
([WHATWG-DOM]) attribute SHOULD be true
and detail
[DOM-LEVEL-3-EVENTS] attribute SHOULD be 0.
Similar to the MouseEvents [DOM-LEVEL-3-EVENTS] the relatedTarget
should be initialized to the element whose bounds the pointer just left (in the case of a pointerover
or pointerenter
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
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 Process Pending Pointer Capture and fire the gotpointercapture
and lostpointercapture
events.
The user agent MUST run the following steps when implicitly releasing pointer capture as well as when firing Pointer Events that are not gotpointercapture
or lostpointercapture
.
lostpointercapture
at the pointer capture target override node.
gotpointercapture
at the pending pointer capture target override.
Below are the event types defined in this specification.
In the case of the primary pointer, these events (with the exception of gotpointercapture
and lostpointercapture
) may also fire compatibility mouse events.
pointerover
eventA user agent MUST fire a pointer event named pointerover
when a pointing device is moved into the hit test boundaries of an element. Note that setPointerCapture
or releasePointerCapture
might have changed the hit test target and while a pointer is captured it is considered to be always inside the boundaries of the capturing element for the purpose of firing boundary events. A user agent MUST also fire this event prior to firing a pointerdown
event for devices that do not support hover (see pointerdown
).
pointerenter
eventA user agent MUST fire a pointer event named pointerenter
when a pointing device is moved into the hit test boundaries of an element or one of its descendants, including as a result of a pointerdown
event from a device that does not support hover (see pointerdown
). Note that setPointerCapture
or releasePointerCapture
might have changed the hit test target and while a pointer is captured it is considered to be always inside the boundaries of the capturing element for the purpose of firing boundary events. This event type is similar to pointerover
, but differs in that it does not bubble.
mouseenter
event described in [DOM-LEVEL-3-EVENTS], and the CSS :hover
pseudo-class described in [CSS21]. See also the pointerleave
event.pointerdown
eventA user agent MUST fire a pointer event named pointerdown
when a pointer enters the active 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 the digitizer. 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.
pointerdown
and pointerup
are not fired for all of the same circumstances as mousedown
and mouseup
. See chorded buttons for more information.For input devices that do not support hover, a user agent MUST also fire a pointer event named pointerover
followed by a pointer event named pointerenter
prior to dispatching the pointerdown
event.
pointerdown
event (if the isPrimary
property is true
). This sets the PREVENT MOUSE EVENT FLAG on the pointer. Note, however, that this does not prevent the mouseover
, mouseenter
, mouseout
, or mouseleave
events from firing.pointermove
eventA user agent MUST fire a pointer event named pointermove
when a pointer changes coordinates. Additionally, when a pointer changes button state, pressure, tangential pressure, tilt, twist, or contact geometry (e.g. width
and height
) and the circumstances produce no other pointer events defined in this specification then a user agent MUST fire a pointer event named pointermove
.
pointerup
eventA user agent MUST fire a pointer event named pointerup
when a pointer leaves the active 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 the digitizer. 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 input devices that do not support hover, a user agent MUST also fire a pointer event named pointerout
followed by a pointer event named pointerleave
after dispatching the pointerup
event.
pointerdown
and pointerup
are not fired for all of the same circumstances as mousedown
and mouseup
. See chorded buttons for more information.pointercancel
eventA user agent MUST fire a pointer event named pointercancel
in the following circumstances:
pointerdown
event, if the pointer is subsequently used to manipulate the page viewport (e.g. panning or zooming).preventDefault
on the dragstart
event)
there will be no pointercancel
event.After firing the pointercancel
event, a user agent MUST also fire a pointer event named pointerout
followed by firing a pointer event named pointerleave
.
This section is non-normative.
Examples of scenarios in which a user agent might determine that a pointer is unlikely to continue to produce events include:
Methods for changing the device's screen orientation, recognizing accidental input, or using a pointer to manipulate the viewport (e.g. panning or zooming) are out of scope for this specification.
pointerout
eventA user agent MUST fire a pointer event named pointerout
when any of the following occurs:
setPointerCapture
or releasePointerCapture
might have changed the hit test target and while a pointer is captured it is considered to be always inside the boundaries of the capturing element for the purpose of firing boundary events.pointerup
event for a device that does not support hover (see pointerup
).pointercancel
event (see pointercancel
).pointerleave
eventA user agent MUST fire a pointer event named pointerleave
when a pointing device is moved out of the hit test boundaries of an element and all of its descendants, including as a result of a pointerup
and pointercancel
events from a device that does not support hover (see pointerup
and pointercancel
). Note that setPointerCapture
or releasePointerCapture
might have changed the hit test target and while a pointer is captured it is considered to be always inside the boundaries of the capturing element for the purpose of firing boundary events. User agents MUST also fire a pointer event named pointerleave
when a pen stylus leaves hover range detectable by the digitizer. This event type is similar to pointerout
, but differs in that it does not bubble and that it MUST not be fired until the pointing device has left the boundaries of the element and the boundaries of all of its descendants.
mouseleave
event described in [DOM-LEVEL-3-EVENTS], and the CSS :hover
pseudo-class described in [CSS21]. See also the pointerenter
event.gotpointercapture
eventA user agent MUST fire 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 the Setting Pointer Capture and Process Pending Pointer Capture sections.
lostpointercapture
eventA user agent MUST fire 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. Subsequent events for the pointer follow normal hit testing mechanisms (out of scope for this specification) for determining the event target. See the Releasing Pointer Capture, Implicit Release of Pointer Capture, and Process Pending Pointer Capture sections.
Element
interfaceThe following section describes extensions to the existing Element
interface, defined in [HTML5], to facilitate the setting and releasing of pointer capture.
partial interface Element
{
void setPointerCapture
(long pointerId);
void releasePointerCapture
(long pointerId);
boolean hasPointerCapture
(long pointerId);
};
setPointerCapture
Sets pointer capture for the pointer identified by the argument pointerId
to the element on which this method is invoked. For subsequent events of the pointer, the capturing target will substitute the normal hit testing result as if the pointer is always over the capturing target, and they MUST always be targeted at this element until capture is released. The pointer MUST be in its active buttons state for this method to be effective, otherwise it fails silently. Throws a DOMException
with the name InvalidPointerId
when the provided method's argument does not match any of the active pointers.
releasePointerCapture
Releases pointer capture for the pointer identified by the argument pointerId
from the element on which this method is invoked. Subsequent events for the pointer follow normal hit testing mechanisms (out of scope for this specification) for determining the event target. Throws a DOMException
with the name InvalidPointerId
when the provided the method's argument does not match any of the active pointers.
hasPointerCapture
Indicates whether the element on which this method is invoked has pointer capture for the pointer identified by the argument pointerId
. In particular, returns true
if the pending pointer capture target override for pointerId
is set to the element on which this method is invoked, and false
otherwise.
setPointerCapture
, even though that element will not yet have received a gotpointercapture event. As a result it can be useful for detecting implicit pointer capture from inside of a pointerdown event listener.GlobalEventHandlers
interfaceThe following section describes extensions to the existing GlobalEventHandlers
interface, defined in [HTML5], to facilitate the event handler registration.
partial interface GlobalEventHandlers
{
attribute EventHandler ongotpointercapture
;
attribute EventHandler onlostpointercapture
;
attribute EventHandler onpointerdown
;
attribute EventHandler onpointermove
;
attribute EventHandler onpointerup
;
attribute EventHandler onpointercancel
;
attribute EventHandler onpointerover
;
attribute EventHandler onpointerout
;
attribute EventHandler onpointerenter
;
attribute EventHandler onpointerleave
;
};
ongotpointercapture
gotpointercapture
event type.
onlostpointercapture
lostpointercapture
event type.
onpointerdown
pointerdown
event type.
onpointermove
pointermove
event type.
onpointerup
pointerup
event type.
onpointercancel
pointercancel
event type.
onpointerover
pointerover
event type.
onpointerout
pointerout
event type.
onpointerenter
pointerenter
event type.
onpointerleave
pointerleave
event type.
For touch input, the default action of any and all pointer events MUST NOT be a manipulation of the viewport (e.g. panning or zooming).
touch-action
CSS propertyName: | 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. |
The touch-action
CSS property determines whether touch input MAY trigger default behavior supplied by user agent. This includes, but is not limited to, behaviors such as panning or zooming. See the section on touch-action
values.
touch-action
value when determining which default behaviors it should handle.During the execution of a user agent touch behavior, the user agent MUST NOT fire subsequent pointer events for the pointer. The user agent MUST fire a pointer event named pointercancel
(and subsequently a pointerout
event and one or more pointerleave
events) whenever all of the following are true, in order to end the stream of events for the pointer:
pointerdown
event has been sent for the pointer, andpointerup
or pointercancel
event (following the above mentioned pointerdown
) has not yet been sent for the pointer.When a user touches an element, the effect of that touch is determined by the value of the touch-action
property, and the default touch behaviors of the element and its ancestors, as follows:
touch-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 to affect 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 coodinate.touch-action
property of each element between the hit tested element and its nearest ancestor with the default touch behavior (including both the hit tested element and the element with the default touch behavior).touch-action
value will be ignored for the duration of the touch action. For instance, programmatically changing the touch-action
value for an element from auto
to none
as part of a pointerdown
handler script will not result in the user agent aborting or suppressing any default touch behavior for that touch for as long as that pointer is active.touch-action
values of multiple concurrent pointers is out of scope for this specification.touch-action
valuesThe user agent MAY consider touches that begin on the element only for the purposes of scrolling that starts in any of the directions specified by all of the listed values. Once scrolling is started, the direction may be reversed by the user even if scrolls that start in the reversed direction are disallowed. In contrast, when scrolling is restricted to starting along a single axis (eg. pan-y
), the axis cannot be changed during the scroll.
In the case of pan-left
, pan-right
, pan-up
and pan-down
, the direction is interpreted as the opposite of the physical movement in the local coordinate space. For example, pan-up
corresponds to input event sequences where typically screenY
is increasing (i.e. an interaction where the user moves a touch point down the screen) when the element has no effective CSS transforms. If the element is effectively rotated by 90 degrees counter-clockwise, pan-up
would then correspond to input event sequences where screenX
is increasing.
auto
are out of scope for this specification.auto
or none
values are out of scope for this specification.touch-action
property only applies to elements that support both the CSS width
and height
properties (see [CSS21]). This restriction is designed to facilitate user agent optimizations for low-latency touch actions. For elements not supported by default, such as <span>
which is a non-replaced inline element (see [HTML5]), authors can set the display
CSS property to a value, such as block
, that supports width
and height
. Future specifications could extend this API to all elements.The direction-specific pan values are useful for customizing overscroll behavior. For example, to implement a simple pull-to-refresh effect the document's touch-action can be set to pan-x pan-down
whenever the scroll position is 0 and pan-x pan-y
otherwise. This allows pointer event handlers to define the behavior for upward scrolls 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 use pan-y
to ensure it receives pointer events for any horizontal pan operations without interfering with vertical scrolling of the document. When the carousel reaches its right-most extent, it may change its touch-action to pan-y pan-right
so that a subsequent pan operation beyond its extent can scroll the document within the viewport if possible. It's not possible to change the behavior of a pan in the middle of an operation.
auto
user agents typically add 300ms of delay before click
to allow for double-tap gestures to be handled. In these cases, explicitly setting touch-action: none
or touch-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 touches.
</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 touches.
</div>
<div>
Touches 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 touches because
it allows only horizontal panning yet an intermediate ancestor
(between it and the pannable element) only allows vertical panning.
Therefore, no touch behaviors are allowed.
</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>
This section is non-normative.
Pointer capture allows the events for a particular pointer (including any compatibility mouse events) to be retargeted to a particular element other than the normal hit test result of the pointer's location. This is useful in scenarios like a custom slider control (e.g. similar to the [HTML5] <input type="range">
control). Pointer capture can be set on the slider thumb element, allowing the user to slide the control back and forth even if the pointer slides off of the thumb.
Pointer capture is set on an element by calling the element.setPointerCapture(pointerId)
method. When this method is invoked, a user agent MUST run the following steps:
pointerId
provided as the method's argument does not match any of the active pointers, then throw a DOMException
with the name InvalidPointerId
.Element
on which this method is invoked does not participate in its ownerDocument
's tree, throw an exception with the name InvalidStateError
.InvalidStateError
.pointerId
, set the pending pointer capture target override to the Element
on which this method was invoked.Pointer capture is released on an element explicitly by calling the element.releasePointerCapture(pointerId)
method. When this method is called, a user agent MUST run the following steps:
pointerId
provided as the method's argument does not match any of the active pointers and these steps are not being invoked as a result of the implicit release of pointer capture, then throw a DOMException
with the name InvalidPointerId
.Element
with the specified pointerId
, then terminate these steps.pointerId
, clear the pending pointer capture target override, if set.Some input devices (such as touchscreens) implement a "direct manipulation" metaphor where a pointer is intended to act primarily on the UI element it became active upon (providing a physical illusion of direct contact, instead of indirect contact via a cursor that conceptually floats above the UI). Such devices are identified by the InputDeviceCapabilities.pointerMovementScrolls property and should have "implicit pointer capture" behavior as follows.
Direct manipulation devices should behave exactly as if setPointerCapture
was called on the target element just before the invocation of any pointerdown
listeners. The hasPointerCapture
API may be used (eg. within any pointerdown
listener) to determine whether this has occurred. If releasePointerCapture
is not called for the pointer before the next pointer event is fired, then a gotpointercapture event will be dispatched to the target (as normal) indicating that capture is active.
Immediately after firing the pointerup
or pointercancel
events, a user agent MUST clear the pending pointer capture target override for the pointerId
of the pointerup
or pointercancel
event that was just dispatched, and then run Process Pending Pointer Capture steps to fire lostpointercapture
if necessary.
If the user agent supports firing the click
event (see compatibility mouse events) and if in an implicit release scenario both click
and lostpointercapture
events are fired, click
should be fired before lostpointercapture
.
When the pointer capture target override is removed from its ownerDocument
's tree,
clear the pending pointer capture target override and pointer capture target override nodes
and fire a PointerEvent named lostpointercapture
corresponding to the captured pointer at the document.
When a pointer lock ([PointerLock]) is successfully applied on an element, a user agent MUST run the steps as if the releasePointerCapture() method has been called if any element is set to be captured or pending to be captured.
The vast majority of web content existing today codes only to Mouse Events. The following describes an algorithm for how a user agent MAY map generic pointer input to mouse events for compatibility with this content.
The compatibility mapping with mouse events are an OPTIONAL feature of this specification. User agents are encouraged to support the feature for best compatibility with existing legacy content. User agents that do not support compatibility mouse events are still encouraged to support the click
and contextmenu
events (see the note below).
The click
event, defined in [DOM-LEVEL-3-EVENTS], and the contextmenu
event, defined in [HTML5], are not considered compatibility mouse events as they are typically tied to user interface activation and are fired from other input devices, like keyboards.
In user agents that support firing click
and/or contextmenu
, calling preventDefault
during a pointer event typically does not have an effect on whether click
and/or contextmenu
are fired or not. Because they are not compatibility mouse events, user agents typically fire click
and contextmenu
for all pointing devices, including pointers that are not primary pointers.
The relative ordering of these high-level events (click
, contextmenu
, focus
, blur
, etc.) with pointer events is undefined and varies between user agents. For example, in some user agents contextmenu
will often follow a pointerup
, in others it'll often precede a pointerup
or pointercancel
, and in some situations it may be fired without any corresponding pointer event (such as a keyboard shortcut).
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 its ownerDocument
'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 its ownerDocument
'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.
mouseover
, mouseout
, mouseenter
, and mouseleave
events are never prevented (even if the pointer is down).While only the primary pointers can produce compatibility mouse events, multiple primary pointers can be active simultaneously, each producing its own compatibility mouse events. Since all these compatibility events would appear to MouseEvent code to be coming from a single mouse device, user agents are encouraged to guarantee that the compatibility mouse events are consistent from a single device perspective. For mouse transition events (i.e., mouseover
, mouseout
, mouseenter
and mouseleave
), this means the entry/exit state for every event target is valid as implied by [DOM-LEVEL-3-EVENTS]. Users agents SHOULD guarantee this by maintaining the effective 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 the window
, the user agent SHOULD run the following steps:
T
be the target of the pointerdown
, pointerup
or pointermove
event being dispatched. For the pointerleave
event, unset T
.T
and current effective legacy mouse pointer position are both unset or they are uqual, terminate these steps.mouseover
, mouseout
, mouseenter
and mouseleave
events as per [DOM-LEVEL-3-EVENTS] for a mouse moving from the current effective legacy mouse pointer position to T
. Consider an unset value of either current effective legacy mouse pointer position or T
as an out-of-window mouse position.T
.Whenever a user agent is to dispatch a pointer event for a device that supports hover, it SHOULD run the following steps:
isPrimary
property for the pointer event to be dispatched is false
then dispatch the pointer event and terminate these steps.pointerdown
, pointerup
or pointermove
event, or a pointerleave
event at the window
, dispatch compatibility mouse transition events as described in Tracking the effective position of the legacy mouse pointer.pointerdown
and the event was canceled, then set the PREVENT MOUSE EVENT flag for this pointerType
.pointerType
and the pointer event dispatched was:
pointerdown
, then fire a mousedown
event.pointermove
, then fire a mousemove
event.pointerup
, then fire a mouseup
event.pointercancel
, then fire a mouseup
event at the window
.pointerup
or pointercancel
, clear the PREVENT MOUSE EVENT flag for this pointerType
.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:
mousemove
event on an element before clicking it.This requires that user agents provide a different mapping for these types of input devices. Whenever a user agent is to dispatch a pointer event for a device that does not support hover, it SHOULD run the following steps:
isPrimary
property for the pointer event to be dispatched is false
then dispatch the pointer event and terminate these steps.pointerover
and the pointerdown
event has not yet been dispatched for this pointer, then fire a mousemove
event (for compatibility with legacy mouse-specific code).pointerdown
, pointerup
or pointermove
event, or a pointerleave
event at the window
, dispatch compatibility mouse transition events as described in Tracking the effective position of the legacy mouse pointer.pointerdown
and the event was canceled, then set the PREVENT MOUSE EVENT flag for this pointerType
.pointerType
and the pointer event dispatched was:
pointerdown
, then fire a mousedown
event.pointermove
, then fire a mousemove
event.pointerup
, then fire a mouseup
event.pointercancel
, then fire a mouseup
event at the window
.pointerup
or pointercancel
, clear the PREVENT MOUSE EVENT flag for this pointerType
.If the user agent supports both Touch Events (as defined in [TOUCH-EVENTS]) and Pointer Events, the user agent SHOULD NOT generate compatibility mouse events as described in this section as it is likely to introduce compatibility problems for sites that expect mouse events to be generated in accordance with the model outlined in [TOUCH-EVENTS].
The activation of an element (click
) with a primary pointer that does not support hover (e.g. single finger on a touchscreen) would typically produce the following event sequence:
mousemove
pointerover
pointerenter
mouseover
mouseenter
pointerdown
mousedown
pointermove
and mousemove
events, depending on movement of the pointerpointerup
mouseup
click
pointerout
pointerleave
mouseout
mouseleave
If, however, the pointerdown
event is canceled during this interaction then the sequence of events would be:
mousemove
pointerover
pointerenter
mouseover
mouseenter
pointerdown
pointermove
events, depending on movement of the pointerpointerup
click
pointerout
pointerleave
mouseout
mouseleave
Many thanks to lots of people for their proposals and recommendations, some of which are incorporated into this document. The group's Chair acknowledges contributions from the following past and present group members and participants: Mustaq Ahmed, Arthur Barstow, Matt Brubeck, Rick Byers, Cathy Chan, Ted Dinklocker, Dave Fleck, Scott González, Patrick H. Lauke, Sangwhan Moon, Olli Pettay, Jacob Rossi, Doug Schepers, Dave Tapuska, Asir Vedamuthu, Navid Zolghadr
Special thanks to those that helped pioneer the first edition of this model, including especially: Charu Chandiram, Peter Freiling, Nathan Furtwangler, Thomas Olsen, Matt Rakow, Ramu Ramanathan, Justin Rogers, Jacob Rossi, Reed Townsend and Steve Wright.
This section is non-normative.
The following is an informative summary of substantial and major editorial changes between publications of this specification, relative to the first [PointerEvents] specification. See the complete revision history of the Editor's Drafts of this specification.