Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

Element.setPointerCapture — capturing a pointer

The setPointerCapture(pointerId) method directs subsequent events for one pointer to a chosen element, even after the pointer leaves its bounds. It supports dragging with a mouse, touch, or pen.

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

element.setPointerCapture(pointerId)

Call Element.setPointerCapture on an element, usually inside a pointerdown handler, passing event.pointerId. Capture overrides normal position-based target selection, so the element continues receiving events such as pointermove outside its bounds. The method returns undefined; it neither moves nor locks the cursor.

The call sets pending capture: hasPointerCapture(pointerId) can return true immediately, before gotpointercapture. releasePointerCapture(pointerId) releases it explicitly; after pointerup or pointercancel, the browser releases it automatically. Use lostpointercapture to clean up interaction state. Touch input may already have implicit capture.

An identifier that matches no active pointer causes NotFoundError. A disconnected element or active Pointer Lock in its document causes InvalidStateError. Only after the pointer ID, element connectivity, and Pointer Lock checks pass does the method check the remaining conditions: if there is neither a pressed button nor contact, or if the element's document is not the pointer's active document, the method does not set capture and does not throw.

Capture does not disable touch scrolling or zooming; the example uses touch-action: none only on its demonstration area. This is a browser API specified by Pointer Events, not a feature of a particular ECMAScript edition. Having Node 24 does not prove availability: detect the method and test target browsers.

Examples

const pad = document.createElement('div');
pad.textContent = 'Press, move outside, release';
pad.style.cssText = 'width:220px;height:100px;background:lightblue;touch-action:none;user-select:none';
const log = document.createElement('pre');
document.body.append(pad, log);

if (typeof pad.setPointerCapture !== 'function') {
  log.textContent = 'unsupported';
} else {
  let activeId = null;
  pad.addEventListener('pointerdown', (event) => {
    if (activeId !== null) return;
    pad.setPointerCapture(event.pointerId);
    activeId = event.pointerId;
    log.textContent = `pending: ${pad.hasPointerCapture(activeId)}`;
  });
  pad.addEventListener('pointermove', (event) => {
    if (event.pointerId === activeId) {
      log.textContent = 'moving';
    }
  });
  pad.addEventListener('lostpointercapture', (event) => {
    if (event.pointerId === activeId) {
      activeId = null;
      log.textContent = 'released';
    }
  });
}

Result

released

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources