JavaScript Document caretPositionFromPoint() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Method
Decorative image with the word CARETPOSITIONFROMPOINT

Definition

document.caretPositionFromPoint(x, y) maps a point in the viewport to a text insertion position. It returns a CaretPosition with the node (offsetNode) and character offset (offset), or null.

Pass the required arguments shown below. Check return values and browser support before you rely on the result.

Syntax

Call document.caretPositionFromPoint. Start with this line.

JavaScript
document.caretPositionFromPoint(x, y[, options])
CallWhat it does
document.caretPositionFromPoint(x, y[, options])Primary signature.
document.caretPositionFromPoint(...)Call with the arguments your case needs.

Built into the browser. Call caretPositionFromPoint(...) on document — no import required.

Library declarations
JavaScript
document.caretPositionFromPoint(x, y[, options])

Parameters

ParameterDescription
x, yRequired. Viewport coordinates (CSS pixels)
options.shadowRootsOptional. Shadow roots that may contain the caret

Return Value

Return ValueDescription
*CaretPosition or null

JavaScript Examples

Example 1 — Read offsetNode and offset

On click, map the pointer to a caret position inside the text.

JavaScript
document.querySelector("p").addEventListener("click", (e) => {
  if (!document.caretPositionFromPoint) return;

  const pos = document.caretPositionFromPoint(e.clientX, e.clientY);
  if (!pos) {
    console.log("null");
    return;
  }

  console.log(pos.offsetNode.nodeName); // "#text" when on text
  console.log(pos.offset);              // character index
});
Try It Yourself

How It Works

  1. Listen for click. The event gives viewport coordinates.
  2. Call the API. Pass clientX and clientY.
  3. Guard null. Outside text (or invalid point) returns null.
  4. Read fields. offsetNode is often a text node; offset is the index.

Example 2 — Standard API with Legacy Fallback

MDN pattern: prefer caretPositionFromPoint, else non-standard caretRangeFromPoint.

JavaScript
function caretAt(e) {
  if (document.caretPositionFromPoint) {
    const pos = document.caretPositionFromPoint(e.clientX, e.clientY);
    if (!pos) return null;
    return { node: pos.offsetNode, offset: pos.offset };
  }
  if (document.caretRangeFromPoint) {
    const range = document.caretRangeFromPoint(e.clientX, e.clientY);
    if (!range) return null;
    return { node: range.startContainer, offset: range.startOffset };
  }
  return null;
}

document.body.addEventListener("click", (e) => {
  const c = caretAt(e);
  console.log(c ? c.offset : "unsupported / null");
});
Try It Yourself

How It Works

  1. Prefer the standard method. Use CaretPosition fields when available.
  2. Fall back carefully. caretRangeFromPoint is non-standard; map startContainer/startOffset.
  3. Normalize the shape. Return the same { node, offset } from both paths.
  4. Handle missing APIs. Return null when neither method exists.

Example 3 — Support Check and Null Result

Detect the method, then show when a point yields null.

JavaScript
const supported = typeof document.caretPositionFromPoint === "function";
console.log(supported);

if (supported) {
  // Far outside the viewport → typically null
  const pos = document.caretPositionFromPoint(-1, -1);
  console.log(pos); // null
}
Try It Yourself

How It Works

  1. Feature-detect. Newly available APIs need a typeof check on older browsers.
  2. Invalid coordinates. Negative or out-of-viewport points return null (MDN).
  3. No insertion point. Some UI areas also return null.
  4. Always null-check before reading offsetNode.
Compatibility

Browser Support

Document.caretPositionFromPoint() is a browser API marked Baseline 2025 Newly available on MDN (since December 2025). Feature-detect; keep caretRangeFromPoint as a legacy fallback where needed.

✓ Baseline 2025 · Newly available

Document.caretPositionFromPoint()

Supported in the latest major browsers. Older engines may only expose the non-standard caretRangeFromPoint fallback.

New Baseline 2025
Google Chrome Latest (Baseline 2025)
Yes
Microsoft Edge Latest (Baseline 2025)
Yes
Mozilla Firefox Latest (Baseline 2025)
Yes
Apple Safari Latest (Baseline 2025)
Yes
Opera Latest (Baseline 2025)
Yes
Internet Explorer No
No
caretPositionFromPoint() Newly available

Bottom line: Detect support, use clientX/clientY, null-check the result. See the MDN caretPositionFromPoint() reference.

Frequently Asked Questions

It returns a CaretPosition object (or null) for the text insertion point at viewport coordinates x and y — including the DOM node and character offset within that node.
No. MDN marks Document.caretPositionFromPoint() as Baseline 2025 Newly available (since December 2025). It is not Deprecated, Experimental, or Non-standard. Older browsers may still lack it — feature-detect.
A CaretPosition with offsetNode and offset, or null if there is no viewport, coordinates are invalid/outside the viewport, or no text insertion point exists there.
caretPositionFromPoint() is the standard method returning CaretPosition. caretRangeFromPoint() is a non-standard WebKit-era fallback that returns a Range (startContainer / startOffset).
An optional array of ShadowRoot objects. When supplied, the method can return a caret position inside those shadow trees. Otherwise positions inside other shadow DOM may remap to the shadow host.
Use viewport coordinates — typically event.clientX and event.clientY from a click or pointer event, not pageX/pageY.

Next: caretRangeFromPoint()

Learn the non-standard Range-based caret hit-test used as a fallback.

caretRangeFromPoint() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

14 people found this page helpful

JavaScript Document browsingTopics() Method JavaScript Document caretRangeFromPoint() Method