JavaScript Document caretRangeFromPoint() Method

What You’ll Learn

document.caretRangeFromPoint() is a non-standard instance method that returns a Range for the document under viewport coordinates. Learn startContainer / startOffset, when it returns null, shadow DOM limitations, how it compares to caretPositionFromPoint(), and five try-it labs.

Introduction

Before the standard caretPositionFromPoint() API, some browsers (especially WebKit-based engines) exposed document.caretRangeFromPoint(x, y) to answer: “where in the document is the text caret at this pixel?”

MDN: it returns a Range object for the document fragment under the specified coordinates. For a collapsed caret at a click point, you typically read range.startContainer and range.startOffset.

Related tutorials: caretPositionFromPoint(), nodeType, textContent.

Understanding document.caretRangeFromPoint()

An instance method on the page’s document object. Not part of any official specification (MDN).

• Input — viewport x and y (MDN).
• Output — a Range, or null.
• Caret mapping — startContainer + startOffset at the point.
• Null cases — negative coords, outside viewport, or no text entry node (MDN).
• Shadow DOM — unpredictable; use standard API with shadowRoots (MDN).
• Modern path — caretPositionFromPoint() (Baseline 2025).

📝 Syntax

General form of Document.caretRangeFromPoint (MDN):

caretRangeFromPoint(x, y)

Parameters

• x — horizontal position within the current viewport (MDN).
• y — vertical position within the current viewport (MDN).

Return value

A Range, or null (MDN).

Common patterns

// Prefer standard API, fall back to caretRangeFromPoint (MDN)
function getCaretAtPoint(x, y) {
  if (document.caretPositionFromPoint) {
    const pos = document.caretPositionFromPoint(x, y);
    return pos ? { node: pos.offsetNode, offset: pos.offset } : null;
  }
  if (document.caretRangeFromPoint) {
    const range = document.caretRangeFromPoint(x, y);
    return range
      ? { node: range.startContainer, offset: range.startOffset }
      : null;
  }
  return null;
}

paragraph.addEventListener("click", (e) => {
  const caret = getCaretAtPoint(e.clientX, e.clientY);
  console.log(caret);
});

⚖️ caretRangeFromPoint vs caretPositionFromPoint

Examples Gallery

Examples follow MDN Document: caretRangeFromPoint() and the fallback patterns on the caretPositionFromPoint() page.

paragraph.addEventListener("click", (e) => {
  if (!document.caretRangeFromPoint) return;

  const range = document.caretRangeFromPoint(e.clientX, e.clientY);
  if (!range) return;

  console.log({
    nodeName: range.startContainer.nodeName,
    nodeType: range.startContainer.nodeType,
    offset: range.startOffset
  });
});

{ nodeName: "#text", nodeType: 3, offset: 10 }

function getCaretAtPoint(x, y) {
  if (document.caretPositionFromPoint) {
    const pos = document.caretPositionFromPoint(x, y);
    return pos
      ? { node: pos.offsetNode, offset: pos.offset, via: "standard" }
      : null;
  }
  if (document.caretRangeFromPoint) {
    const range = document.caretRangeFromPoint(x, y);
    return range
      ? { node: range.startContainer, offset: range.startOffset, via: "legacy" }
      : null;
  }
  return null;
}

{ node: #text, offset: 8, via: "standard" }
—or— via: "legacy"

if (!document.caretRangeFromPoint) return;

const negative = document.caretRangeFromPoint(-1, -1);
console.log(negative === null); // true (MDN)

true

function insertBreakAtPoint(e) {
  let textNode, offset;

  if (document.caretPositionFromPoint) {
    const pos = document.caretPositionFromPoint(e.clientX, e.clientY);
    textNode = pos?.offsetNode;
    offset = pos?.offset;
  } else if (document.caretRangeFromPoint) {
    const range = document.caretRangeFromPoint(e.clientX, e.clientY);
    textNode = range?.startContainer;
    offset = range?.startOffset;
  } else {
    return;
  }

  if (textNode?.nodeType === 3) {
    const replacement = textNode.splitText(offset);
    const br = document.createElement("br");
    textNode.parentNode.insertBefore(br, replacement);
  }
}

(click paragraph — br inserted at startOffset)

const support = {
  caretPositionFromPoint: typeof document.caretPositionFromPoint === "function",
  caretRangeFromPoint: typeof document.caretRangeFromPoint === "function"
};

if (support.caretPositionFromPoint) {
  console.log("Use standard caretPositionFromPoint (MDN)");
} else if (support.caretRangeFromPoint) {
  console.log("Fallback to non-standard caretRangeFromPoint (MDN)");
} else {
  console.log("No caret-from-point API");
}

Use standard caretPositionFromPoint
—or— Fallback to non-standard caretRangeFromPoint

🚀 Common Use Cases

• Legacy browser fallback — when caretPositionFromPoint is missing (MDN).
• Rich text editors — map clicks to text offsets on older WebKit.
• Maintaining old code — understand existing caretRangeFromPoint calls.
• Teaching API evolution — compare non-standard vs Baseline 2025 standard.
• Not for shadow DOM — MDN warns of unpredictable results; use standard API.
• Not for new apps alone — always pair with feature detection and standard-first logic.

📝 Notes

• MDN: Non-standard — not part of any specification.
• Not Deprecated or Experimental on MDN — but not recommended for new code.
• Prefer caretPositionFromPoint() when available (MDN).
• Predates shadow DOM — unpredictable with ShadowRoot (MDN).
• Coordinates are viewport-relative, not document/page coordinates.
• Related: nodeType, textContent.

💡 Best Practices