JavaScript Document elementFromPoint() Method

What You’ll Learn

document.elementFromPoint() is an instance method that returns the topmost Element at viewport coordinates (see MDN Document: elementFromPoint()). Learn x / y, when the result is null, how pointer-events: none is ignored, iframe notes, how this differs from caret APIs, and five try-it labs.

Introduction

Hit-testing answers a simple question: which element is under this point on the screen? Games, custom drag handles, and “what is under the mouse?” tools all need that answer.

document.elementFromPoint(x, y) returns the topmost Element at those coordinates. MDN: coordinates are relative to the viewport (not the full document scroll height).

MDN tip: if you need a position inside text (caret offset), use caretPositionFromPoint() instead.

Related tutorials: caretPositionFromPoint(), caretRangeFromPoint(), createElement().

Understanding document.elementFromPoint()

An instance method on Document (usually document.elementFromPoint(x, y) on the live page).

• x — horizontal coordinate from the left edge of the viewport (MDN).
• y — vertical coordinate from the top edge of the viewport (MDN).
• Return value — the topmost Element at that point (MDN).
• null — outside the visible document bounds, or either coordinate is negative (MDN).
• pointer-events: none — ignored; the element below is returned (MDN).
• iframes — if the point hits another document, the parent element (the <iframe>) is returned (MDN).

📝 Syntax

General form of Document.elementFromPoint (MDN):

elementFromPoint(x, y)

Parameters

• x — horizontal coordinate of a point, relative to the left edge of the current viewport (MDN).
• y — vertical coordinate of a point, relative to the top edge of the current viewport (MDN).

Return value

The topmost Element object located at the specified coordinates (MDN), or null when the point is invalid / outside (MDN).

Exceptions

None highlighted on MDN for this method.

MDN example

function changeColor(newColor) {
  const elem = document.elementFromPoint(2, 2);
  elem.style.color = newColor;
}

document.querySelectorAll("button").forEach((button) => {
  button.addEventListener("click", (event) => {
    changeColor(event.target.textContent.toLowerCase());
  });
});

⚖️ elementFromPoint vs related hit-test APIs

Examples Gallery

Examples follow MDN Document: elementFromPoint() and practical viewport hit-test patterns.

function changeColor(newColor) {
  const elem = document.elementFromPoint(2, 2);
  if (!elem) return;
  elem.style.color = newColor;
}

changeColor("blue");
console.log(document.elementFromPoint(2, 2).tagName);

P

document.addEventListener("mousemove", (event) => {
  const el = document.elementFromPoint(event.clientX, event.clientY);
  console.log(el ? el.tagName : "null");
});

DIV
(as you move over different elements)

console.log(document.elementFromPoint(-1, 10)); // null
console.log(document.elementFromPoint(10, -1)); // null
console.log(document.elementFromPoint(10, 10) !== null); // usually true

null
null
true

// #overlay has pointer-events: none and covers #target
const box = document.getElementById("target");
const rect = box.getBoundingClientRect();
const x = rect.left + rect.width / 2;
const y = rect.top + rect.height / 2;

const el = document.elementFromPoint(x, y);
console.log(el && el.id); // "target" (not "overlay")

target

const card = document.getElementById("card");
const r = card.getBoundingClientRect();
const midX = r.left + r.width / 2;
const midY = r.top + r.height / 2;

const hit = document.elementFromPoint(midX, midY);
console.log(hit === card || card.contains(hit)); // true

true

🚀 Common Use Cases

• Inspect under the cursor — debug overlays and custom inspectors.
• Drag / drop helpers — find the drop target under a pointer.
• Games / canvases beside DOM — see which HTML control sits at a point.
• Ignore ghost overlays — rely on pointer-events: none (MDN).
• Not for text offsets — use caretPositionFromPoint (MDN).
• Stacked layers — consider elementsFromPoint when you need every element.

📝 Notes

• MDN: Baseline Widely available since July 2015.
• Coordinates are viewport-relative (MDN).
• Returns the topmost Element, or null outside / for negative coords (MDN).
• pointer-events: none elements are ignored (MDN).
• For text caret offsets, prefer caretPositionFromPoint() (MDN).
• Related: caretPositionFromPoint(), caretRangeFromPoint(), createTreeWalker().

💡 Best Practices