JavaScript Document caretPositionFromPoint() Method

What You’ll Learn

document.caretPositionFromPoint() is an instance method that maps viewport coordinates to a text caret position. Learn the CaretPosition return value (offsetNode, offset), the shadowRoots option, when it returns null, MDN’s click-to-split example, and the caretRangeFromPoint fallback.

Introduction

When a user clicks on text, you often need to know which character they clicked nearest to—not just which element. Rich text editors, custom selection tools, and inline formatting all depend on mapping pointer coordinates to a DOM text offset.

MDN: Document.caretPositionFromPoint(x, y) returns a CaretPosition object containing the DOM node, along with the caret and caret’s character offset within that node. Coordinates are viewport-relative (like clientX / clientY from a mouse event).

Related tutorials: nodeType, textContent, append(), Document constructor.

Understanding document.caretPositionFromPoint()

An instance method on the page’s document object (CSSOM View Module).

• Input — horizontal and vertical coordinates in the viewport (MDN).
• Output — CaretPosition with offsetNode and offset, or null.
• Text nodes — offset is a character index in the text node.
• Element nodes — offset may be a child index (MDN shadow example).
• shadowRoots — optional array to resolve positions inside supplied shadow trees (MDN).
• Fallback — older browsers may only have non-standard document.caretRangeFromPoint() (MDN).

📝 Syntax

General forms of Document.caretPositionFromPoint (MDN):

caretPositionFromPoint(x, y)
caretPositionFromPoint(x, y, options)

Parameters

• x — horizontal coordinate of a point (MDN).
• y — vertical coordinate of a point (MDN).
• options (optional) — may include:
  • shadowRoots — array of ShadowRoot objects for shadow DOM resolution (MDN).

Return value

A CaretPosition object or null (MDN).

When null is returned (MDN)

• No viewport associated with the document.
• x or y are negative or outside the viewport region.
• Coordinates indicate a point where no text insertion point could be inserted.

Common patterns

// From a click event
paragraph.addEventListener("click", (e) => {
  const pos = document.caretPositionFromPoint(e.clientX, e.clientY);
  if (!pos) return;
  console.log(pos.offsetNode, pos.offset);
});

// With shadow DOM
document.caretPositionFromPoint(x, y, { shadowRoots: [shadow] });

// Fallback for older WebKit
if (document.caretPositionFromPoint) {
  pos = document.caretPositionFromPoint(x, y);
} else if (document.caretRangeFromPoint) {
  const range = document.caretRangeFromPoint(x, y);
  // range.startContainer, range.startOffset
}

⚖️ caretPositionFromPoint vs caretRangeFromPoint

Examples Gallery

Examples follow MDN Document: caretPositionFromPoint(). Click the try-it paragraphs to explore caret positions interactively.

paragraph.addEventListener("click", (e) => {
  const pos = document.caretPositionFromPoint(e.clientX, e.clientY);
  if (!pos) return;

  console.log({
    nodeName: pos.offsetNode.nodeName,
    nodeType: pos.offsetNode.nodeType,
    offset: pos.offset
  });
});

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

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

{ node: #text, offset: 8, api: "caretPositionFromPoint" }

const inside = document.caretPositionFromPoint(100, 100);
const negative = document.caretPositionFromPoint(-1, -1);

console.log(inside !== null);   // true (if point is over text)
console.log(negative === null); // true (MDN)

true
true

const host = document.querySelector("#host");
const shadow = host.attachShadow({ mode: "open" });
shadow.innerHTML = "<span>Shadow text</span>";

// Without shadowRoots — may remap to host
const outer = document.caretPositionFromPoint(x, y);

// With shadowRoots — resolves inside shadow tree (MDN)
const inner = document.caretPositionFromPoint(x, y, {
  shadowRoots: [shadow]
});

With shadowRoots: offsetNode is #text inside shadow
Without: offsetNode may be host element

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 — line break inserted at caret offset)

🚀 Common Use Cases

• Rich text editors — place the caret where the user clicked.
• Custom selection — start/end ranges from pointer coordinates.
• Inline annotations — insert markers at a precise character offset.
• Click-to-edit — split or wrap text nodes at the clicked position (MDN).
• Shadow DOM apps — pass shadowRoots for web components.
• Progressive enhancement — fall back to caretRangeFromPoint on older engines.

📝 Notes

• MDN: Baseline 2025 (newly available since December 2025).
• Not Deprecated, Experimental, or Non-standard.
• Coordinates are viewport-relative, not page/document coordinates.
• caretRangeFromPoint() is a non-standard fallback (MDN examples).
• Use shadowRoots when resolving caret positions inside open shadow trees.
• Related: nodeType, textContent, append().

💡 Best Practices