CKTIS / JavaScript
Pointer capture: commit or abort a drag
Track one drag by `pointerId` and finish it only once: commit on release or abort on cancellation or early loss of capture.
Version: Current web platform; runtime support varies
Syntax
// Handler sketch: supply the element and the five callbacks in your application.
element.addEventListener("pointerdown", onDown);
element.addEventListener("pointermove", onMove);
element.addEventListener("pointerup", onUp);
element.addEventListener("pointercancel", onCancel);
element.addEventListener("lostpointercapture", onLostCapture);
// In onDown, after accepting the pointer for the drag:
// element.setPointerCapture(event.pointerId);
// In onMove, only if the active drag should release capture early:
// element.releasePointerCapture(event.pointerId);Start by saving the pointerId you accept in pointerdown. That event fires when the first mouse button goes down or when a finger or pen tip makes contact. Update the drag only on pointermove events with the saved ID. A move can report a change in position or another property such as pressure, and it can fire while hovering.
To keep tracking the drag outside the element, call element.setPointerCapture(pointerId). Direct touch can set capture implicitly. If you need to give up capture early, call releasePointerCapture(). Both methods can throw NotFoundError if the ID does not identify an active pointer.
Commit on pointerup, when the finger or pen lifts or the last held mouse button is released. Unlike mousedown and mouseup, pointerdown and pointerup do not fire for every mouse button change. Discard temporary state on pointercancel: the browser has interrupted the interaction, for example to take over a scroll or zoom gesture.
Clear the saved ID in either case so the browser's automatic release of capture after pointerup or pointercancel does not finish the drag a second time. lostpointercapture reports loss of capture, not necessarily the end of contact. Abort only if the drag is still active and the event matches its ID.
Capture does not block browser gestures: use CSS touch-action to declare gesture handling beforehand, and limit none to the area that needs it. These are web platform APIs, not part of ECMAScript 2024; availability depends on the runtime.
Examples
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Drag with pointer capture</title>
<style>
#pad {
position: fixed;
top: 16px;
left: 16px;
z-index: 9999;
width: 220px;
height: 100px;
padding: 12px;
background: #def;
color: #123;
border: 2px solid #246;
touch-action: none;
user-select: none;
}
</style>
</head>
<body>
<div id="pad">Start dragging here</div>
<script>
(() => {
const pad = document.getElementById('pad');
let activeId = null;
let moved = false;
pad.addEventListener('pointerdown', (event) => {
if (activeId !== null || event.button !== 0) return;
pad.setPointerCapture(event.pointerId);
activeId = event.pointerId;
moved = false;
console.log('pointerdown');
});
pad.addEventListener('pointermove', (event) => {
if (event.pointerId !== activeId) return;
if (!moved) {
moved = true;
console.log('pointermove');
}
if (event.shiftKey && pad.hasPointerCapture(event.pointerId)) {
pad.releasePointerCapture(event.pointerId);
}
});
function finish(event, result) {
if (event.pointerId !== activeId) return;
activeId = null;
console.log(`${event.type}: ${result}`);
}
pad.addEventListener('pointerup', (event) => finish(event, 'commit'));
pad.addEventListener('pointercancel', (event) => finish(event, 'abort'));
pad.addEventListener('lostpointercapture', (event) => finish(event, 'abort'));
})();
</script>
</body>
</html>Result
pointerdown pointermove pointerup: commit
Save the example as an HTML file, open it in a browser, and watch the developer console. Start a primary-button drag inside the box and release outside without holding Shift. On a separate drag, start moving first, then hold Shift and keep moving without releasing the button to test early capture loss. The `pointermove` line appears at most once per drag.
Related lessons
- JavaScript · Lesson 35 · Intermediate · Version: 3