JavaScript Element setCapture() Method

What You’ll Learn

Element.setCapture() is a deprecated, non-standard instance method that retargets mouse events to an element after mousedown. Learn MDN’s coordinate-tracking demo, the retargetToElement flag, document.releaseCapture() cleanup, feature detection, and why setPointerCapture() replaced it—plus five try-it labs aligned with MDN.

Introduction

When a user presses the mouse button on an element and drags, the pointer can leave that element’s bounds. Normally, mousemove events would stop targeting the original element. Legacy Gecko code used setCapture() to keep receiving mouse events until the button was released.

Call element.setCapture(retargetToElement) during a mousedown handler (MDN). Capture ends when the user releases the mouse button or when document.releaseCapture() is called.

This page is part of JavaScript Element. Pair with MouseEvent, EventTarget, and scrollIntoViewIfNeeded() (another non-standard Element API).

Understanding the setCapture() Method

Calling el.setCapture() during mousedown redirects subsequent mouse events to el until capture is released. It was introduced for Gecko 2.0 mouse-capture scenarios (MDN).

• It is an instance method on Element.
• retargetToElement — if true, all events target this element; if false, descendants may also receive events (MDN).
• Returns undefined.
• Deprecated and non-standard on MDN — not part of any specification.
• Ends on mouse button release or document.releaseCapture() (MDN).
• Modern alternative: setPointerCapture() / releasePointerCapture().

📝 Syntax

General form of Element.setCapture (MDN):

setCapture(retargetToElement)

Parameters

Return value

Notes

• Call during mousedown handling (MDN).
• Capture ends on mouse button release or document.releaseCapture() (MDN).
• The element may not scroll fully to top/bottom depending on layout (MDN).

Common patterns

const btn = document.getElementById("myButton");

function onMouseDown(e) {
  if (!e.target.setCapture) return;
  e.target.setCapture();
  e.target.addEventListener("mousemove", onMouseMove);
}

function onMouseUp(e) {
  e.target.removeEventListener("mousemove", onMouseMove);
}

function onMouseMove(e) {
  console.log(e.clientX, e.clientY);
}

if (btn.setCapture) {
  btn.addEventListener("mousedown", onMouseDown);
  btn.addEventListener("mouseup", onMouseUp);
}

Examples Gallery

Examples follow MDN Element.setCapture() patterns. Use View Output or Try It Yourself for each case. Note: this API may be unavailable in your browser—examples include feature detection.

function mouseDown(e) {
  e.target.setCapture();
  e.target.addEventListener("mousemove", mouseMoved);
}

function mouseUp(e) {
  e.target.removeEventListener("mousemove", mouseMoved);
}

function mouseMoved(e) {
  const output = document.getElementById("output");
  output.textContent = `Position: ${e.clientX}, ${e.clientY}`;
}

const btn = document.getElementById("myButton");
if (btn.setCapture) {
  btn.addEventListener("mousedown", mouseDown);
  btn.addEventListener("mouseup", mouseUp);
}

Position: 142, 88

const panel = document.getElementById("panel");

panel.addEventListener("mousedown", (e) => {
  if (!panel.setCapture) return;
  // true — all events go to panel only (MDN)
  panel.setCapture(true);
});

panel.addEventListener("mouseup", () => {
  // capture ends automatically on button release (MDN)
});

capture: true

const btn = document.getElementById("myButton");
const output = document.getElementById("output");

if (btn.setCapture) {
  btn.addEventListener("mousedown", (e) => e.target.setCapture());
  output.textContent = "setCapture supported";
} else {
  output.textContent =
    "Sorry, no setCapture support in this browser";
}

Sorry, no setCapture support in this browser

const handle = document.getElementById("handle");

handle.addEventListener("mousedown", (e) => {
  if (!handle.setCapture) return;
  handle.setCapture();
  handle.addEventListener("mousemove", onMove);
});

function onMove(e) {
  if (e.clientY < 10 && document.releaseCapture) {
    document.releaseCapture();
    handle.removeEventListener("mousemove", onMove);
  }
}

released

const slider = document.getElementById("slider");

slider.addEventListener("pointerdown", (e) => {
  slider.setPointerCapture(e.pointerId);
});

slider.addEventListener("pointermove", (e) => {
  if (slider.hasPointerCapture(e.pointerId)) {
    console.log(e.clientX, e.clientY);
  }
});

slider.addEventListener("pointerup", (e) => {
  slider.releasePointerCapture(e.pointerId);
});

120 45

🚀 Common Use Cases

• Legacy drag handles that must keep receiving mousemove outside the element (Gecko-only).
• Custom slider or drawing tools in old Firefox/XUL-era codebases.
• Understanding why modern apps use setPointerCapture() instead.
• Migrating maintenance code that still calls setCapture() on mousedown.
• Pairing with document.releaseCapture() for early cancellation.
• Teaching event retargeting concepts before learning Pointer Events.

📝 Notes

• Deprecated and non-standard on MDN — not part of any specification.
• MDN: never had much cross-browser support; avoid in new production code.
• Modern replacement: element.setPointerCapture(pointerId) (Pointer Events).
• Call during mousedown; ends on mouse button release or document.releaseCapture() (MDN).
• Element may not scroll fully to top/bottom depending on layout (MDN).
• Related: MouseEvent, EventTarget, setAttributeNS(), JavaScript hub.

💡 Best Practices