What event occurs when the user clicks the mouse within the controls boundaries?

The following trivial example uses the mouseenter event to change the border on the <div> when the mouse enters the space allotted to it. It then adds an item to the list with the number of the mouseenter or mouseleave event.

HTML

<div id='mouseTarget'> <ul id="unorderedList"> <li>No events yet!</li> </ul> </div>

CSS

Styling the <div> to make it more visible.

#mouseTarget { box-sizing: border-box; width:15rem; border:1px solid #333; }

JavaScript

Result

Much of today's web content assumes the user's pointing device will be a mouse. However, since many devices support other types of pointing input devices, such as pen/stylus and touch surfaces, extensions to the existing pointing device event models are needed. Pointer events address that need.

Note: Pointer events are not available in Web Workers.

Pointer events are DOM events that are fired for a pointing device. They are designed to create a single DOM event model to handle pointing input devices such as a mouse, pen/stylus or touch (such as one or more fingers).

The pointer is a hardware-agnostic device that can target a specific set of screen coordinates. Having a single event model for pointers can simplify creating Web sites and applications and provide a good user experience regardless of the user's hardware. However, for scenarios when device-specific handling is desired, pointer events defines a pointerType property to inspect the device type which produced the event.

The events needed to handle generic pointer input are analogous to mouse events (mousedown/pointerdown, mousemove/pointermove, etc.). Consequently, pointer event types are intentionally similar to mouse event types.

Additionally, a pointer event contains 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. In fact, the PointerEvent interface inherits all of the MouseEvent properties, thus facilitating the migration of content from mouse events to pointer events.

A sensing device with a surface that can detect contact. Most commonly, the sensing device is a touch-enabled screen that can sense input from an input device such as a pen, stylus, or finger. Some sensing devices can detect the close proximity of the input device, and the state is expressed as a hover following the mouse.

The process the browser uses to determine a target element for a pointer event. Typically, this is determined by considering the pointer's location and also the visual layout of elements in a document on screen media.

A hardware-agnostic representation of input devices that can target a specific coordinate (or set of coordinates) on a screen. Examples of pointer input devices are mouse, pen/stylus, and touch contacts.

This example registers a handler for every event type for the given element.

<html lang="en"> <script> function over_handler(event) { } function enter_handler(event) { } function down_handler(event) { } function move_handler(event) { } function up_handler(event) { } function cancel_handler(event) { } function out_handler(event) { } function leave_handler(event) { } function gotcapture_handler(event) { } function lostcapture_handler(event) { } function init() { const el = document.getElementById("target"); el.onpointerover = over_handler; el.onpointerenter = enter_handler; el.onpointerdown = down_handler; el.onpointermove = move_handler; el.onpointerup = up_handler; el.onpointercancel = cancel_handler; el.onpointerout = out_handler; el.onpointerleave = leave_handler; el.gotpointercapture = gotcapture_handler; el.lostpointercapture = lostcapture_handler; } </script> <body onload="init();"> <div id="target">Touch me…</div> </body> </html>

This example illustrates accessing all of a pointer event's properties.

<html lang="en"> <script> const id = -1; function process_id(event) { } function process_mouse(event) { } function process_pen(event) { } function process_touch(event) { } function process_tilt(tiltX, tiltY) { } function process_pressure(pressure) { } function process_non_primary(event) { } function down_handler(ev) { const area = ev.width * ev.height; if (id === ev.identifier) process_id(ev); switch (ev.pointerType) { case "mouse": process_mouse(ev); break; case "pen": process_pen(ev); break; case "touch": process_touch(ev); break; default: console.log(`pointerType ${ev.pointerType} is not supported`); } if (ev.tiltX !== 0 && ev.tiltY !== 0) process_tilt(ev.tiltX, ev.tiltY); process_pressure(ev.pressure); if (!ev.isPrimary) process_non_primary(ev); } function init() { const el = document.getElementById("target"); el.onpointerdown = down_handler; } </script> <body onload="init();"> <div id="target">Touch me…</div> </body> </html>

In some scenarios there may be multiple pointers (for example a device with both a touchscreen and a mouse) or a pointer supports multiple contact points (for example a touchscreen that supports multiple finger touches). The application can use the isPrimary property to identify a master pointer among the set of active pointers for each pointer type. If an application only wants to support a primary pointer, it can ignore all pointer events that are not primary.

For mouse there is only one pointer, so it will always be the primary pointer. For touch input, a pointer is considered primary if the user touched the screen when there were no other active touches. For pen and stylus input, a pointer is considered primary if the user's pen initially contacted the screen when there were no other active pens contacting the screen.

The touch-action CSS property is used to specify whether or not the browser should apply its default (native) touch behavior (such as zooming or panning) to a region. This property may be applied to all elements except: non-replaced inline elements, table rows, row groups, table columns, and column groups.

A value of auto means the browser is free to apply its default touch behavior (to the specified region) and the value of none disables the browser's default touch behavior for the region. The values pan-x and pan-y, mean that touches that begin on the specified region are only for horizontal and vertical scrolling, respectively. The value manipulation means the browser may consider touches that begin on the element are only for scrolling and zooming.

In the following example, the browser's default touch behavior is disabled for the div element.

<html lang="en"> <body> <div style="touch-action:none;">Can't touch this…</div> </body> </html>

In the following example, default touch behavior is disabled for some button elements.

button#tiny { touch-action: none; }

In the following example, when the target element is touched, it will only pan in the horizontal direction.

#target { touch-action: pan-x; }

Although the pointer event interfaces enable applications to create enhanced user experiences on pointer enabled devices, the reality is the vast majority of today's web content is designed to only work with mouse input. Consequently, even if a browser supports pointer events, the browser must still process mouse events so content that assumes mouse-only input will work as is without direct modification. Ideally, a pointer enabled application does not need to explicitly handle mouse input. However, because the browser must process mouse events, there may be some compatibility issues that need to be handled. This section contains information about pointer event and mouse event interaction and the ramifications for application developers.

The browser may map generic pointer input to mouse events for compatibility with mouse-based content. This mapping of events is called compatibility mouse events. Authors can prevent the production of certain compatibility mouse events by canceling the pointerdown event but note that:

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.
The mouseover, mouseout, mouseenter, and mouseleave events are never prevented (even if the pointer is down).

Here are some best practices to consider when using pointer events:

Minimize the amount of work performed in event handlers.
Add the event handlers to a specific target element (rather than the entire document or nodes higher up in the document tree).
The target element (node) should be large enough to accommodate the largest contact surface area (typically a finger touch). If the target area is too small, touching it could result in firing other events for adjacent elements.

BCD tables only load in the browser

Some additional values have been defined for the css touch-action property as part of the Pointer Events specification, but currently those values have limited implementation support.