A unified event system for the web platform
A polyfill implementation of the Pointer Events Specification.
Mouse events and Touch events are fundamentally different beasts in browsers today, and that makes it hard to write cross-platform apps.
For example, a simple finger paint app needs plenty of work to behave correctly with mouse and touch:
Current platforms that implement touch events also provide mouse events for backward compatibility; however, only a subset of mouse events are fired and the semantics are changed.
- Mouse events are only fired after the touch sequence ends.
- Mouse events are not fired on elements without a click event handler. One must be attached by default, or directly on the element with “onclick”.
- Click events are not fired if the content of the page changes in a mousemove or mouseover event.
- Click events are fired 300ms after the touch sequence ends.
- More information: Apple Developer Documentation.
Additionally, Touch events are sent only to the element that received the
touchstart. This is fundamentally different than mouse events, which fire on the
element that is under the mouse. To make them behave similarly, touch events
need to be retargeted with document.elementFromPoint
.
These incompatibilities lead to applications having to listen to 2 sets of events, mouse on desktop and touch for mobile.
This forked interaction experience is cumbersome and hard to maintain.
Instead, there should exist a set of events that are normalized such that they behave exactly the same, no matter the source: touch, mouse, stylus, skull implant, etc. To do this right, this normalized event system needs to be available for all the web platform to use.
Thus, PointerEvents!
There are existing implementations of event unification, but each have caveats that we think make them not suitable:
- pointer.js nicely abstracts mouse and touch events, but does not solve the touch event targeting issue, and wraps addEventListener
- Hammer.js requires wrapping all elements in a handler and does not dispatch DOM events
- Sencha’s solution requires the whole Sencha Touch framework
- Microsoft MSPointer Events solve the problem the best, but aren't standardized.
Therefore, we felt the need to create PointerEvents.
Microsoft's implementation of MSPointerEvents differs from the spec they have proposed to the W3C.
The key differences are the naming scheme (MSPointerDown vs pointerdown), and a few property values.
Where possible, MSPointerEvents are used as the base for PointerEvent creation, so the information found in MSPointerEvents is maintained.
PointerEvents should work on all "Evergreen" (self-updating) browsers.
It has been tested on Chrome, Firefox, Opera, and IE 10.
The PointerEvents library listens to native platform events on the document level and dispatches new DOM events to the original target. This means that we can utilize the native event bubbling, allow for capturing, and you can still listen to those platform events if you choose. In addition, our architecture is very modular, so any pieces a developer doesn't can be excluded. This keeps the code base small and nimble. The events generated by PointerEvents include all the information that can be expected from MouseEvents, and other modules can add even more information.
pointermove
: a pointer moves, similar to touchmove or mousemove.pointerdown
: a pointer is activated, or a device button held.pointerup
: a pointer is deactivated, or a device button released.pointerover
: a pointer crosses into an element.pointerout
: a pointer leaves an element.pointercancel
: a pointer will no longer generate events.
The goal of this library is to provide a standards compliant polyfill for Pointer Events. Gestures are provided in the upcoming PointerGestures library.