JavaScript Document caretRangeFromPoint() Method

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

Definition

document.caretRangeFromPoint(x, y) maps a viewport point to a Range for the text insertion position. Read startContainer and startOffset — or get null when there is no valid caret there.

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

Syntax

Call document.caretRangeFromPoint. Start with this line.

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

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

Library declarations
JavaScript
document.caretRangeFromPoint(x, y)

Parameters

ParameterDescription
x, yRequired. Viewport coordinates (CSS pixels)

Return Value

Return ValueDescription
*Range or null

JavaScript Examples

Example 1 — Read startContainer and startOffset

On click, map the pointer to a Range with the legacy method (when present).

JavaScript
document.querySelector("p").addEventListener("click", (e) => {
  if (!document.caretRangeFromPoint) {
    console.log("unsupported");
    return;
  }

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

  console.log(range.startContainer.nodeName);
  console.log(range.startOffset);
});
Try It Yourself

How It Works

  1. Detect the method. Many engines never expose it (or only Chromium/WebKit lineages).
  2. Pass viewport coords. Use clientX / clientY.
  3. Null-check. Invalid or empty points return null.
  4. Read the Range. startContainer + startOffset describe the caret.

Example 2 — Prefer caretPositionFromPoint, Then Fallback

MDN guidance: use the standard method first; fall back to this non-standard API.

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, via: "standard" };
  }
  if (document.caretRangeFromPoint) {
    const range = document.caretRangeFromPoint(e.clientX, e.clientY);
    if (!range) return null;
    return {
      node: range.startContainer,
      offset: range.startOffset,
      via: "legacy"
    };
  }
  return null;
}

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

How It Works

  1. Try the standard API. Map CaretPosition to a shared shape.
  2. Else use the Range API. Map startContainer/startOffset the same way.
  3. Tag the path. via helps you see which branch ran in demos.
  4. One app interface. Callers only need { node, offset }.

Example 3 — Support Check and Null Result

Detect the method, then show null for invalid coordinates.

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

if (supported) {
  console.log(document.caretRangeFromPoint(-1, -1)); // null
}
Try It Yourself

How It Works

  1. Feature-detect. Non-standard APIs are uneven across browsers.
  2. Invalid coords. Negative or out-of-viewport points return null (MDN).
  3. No text node. Some UI areas also return null.
  4. Always guard before reading startContainer.
Compatibility

Browser Support

Document.caretRangeFromPoint() is Non-standard on MDN and not in any specification. Support is historically Chromium / WebKit oriented. Prefer the standard caretPositionFromPoint() API.

✓ Non-standard

Document.caretRangeFromPoint()

Legacy caret hit-test returning a Range. Feature-detect; do not assume Firefox or Safari parity with Chromium.

Legacy Non-standard API
Google Chrome Supported (legacy)
Yes
Microsoft Edge Supported (Chromium)
Yes
Opera Supported (Chromium)
Yes
Apple Safari WebKit lineage / check
Partial
Mozilla Firefox Often unsupported
No
Internet Explorer No
No
caretRangeFromPoint() Fallback only

Bottom line: Use as a fallback behind caretPositionFromPoint(). See the MDN caretRangeFromPoint() reference.

Frequently Asked Questions

It returns a Range object (or null) for the document fragment under viewport coordinates x and y — typically with startContainer and startOffset describing the caret position.
MDN marks it Non-standard only — not Deprecated or Experimental. It is not part of any official specification. Prefer caretPositionFromPoint() when available.
Use document.caretPositionFromPoint() on supporting browsers. It is standard and can work with shadowRoots. Keep caretRangeFromPoint() only as a legacy fallback.
A Range, or null if x/y are negative, outside the viewport, or there is no text entry node at that point.
MDN warns it predates shadow DOM and can return unpredictable, implementation-specific results when ShadowRoot objects are present. Prefer caretPositionFromPoint() with shadowRoots.
For a caret at a single point: range.startContainer ≈ pos.offsetNode and range.startOffset ≈ pos.offset.

Next: clear()

Continue with the next Document method in the tutorial series.

clear() tutorial →

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)

12 people found this page helpful

JavaScript Document caretPositionFromPoint() Method JavaScript Document clear() Method