Document.caretPositionFromPoint()

  • Revision slug: DOM/document.caretPositionFromPoint
  • Revision title: document.caretPositionFromPoint
  • Revision id: 362257
  • Created:
  • Creator: fscholz
  • Is current revision? No
  • Comment

Revision Content

Summary

This method is used to retrieve the caret position in a document based on two coordinates. A {{domxref("CaretPosition")}} is returned, containing the found DOM node and the character offset in that node.

Syntax

var cp = document.caretPositionFromPoint(float x, float y);

Parameters

x
Horizontal point on the page at where to determine the caret position.
y
Vertical point on the page at where to determine the caret position.

Return value

A {{domxref("CaretPosition")}}. Null, if x or y are negative or greater than the viewport.

Example

Basic demo: When clicking in a paragraph insert a line break at the caret position:

function insertBreakAtPoint(e) {

    var range;
    var textNode;
    var offset;

    // standard
    if (document.caretPositionFromPoint) {
        range = document.caretPositionFromPoint(e.pageX, e.pageY);
        textNode = range.offsetNode;
        offset = range.offset;
        
    // WebKit
    } else if (document.caretRangeFromPoint) {
        range = document.caretRangeFromPoint(e.pageX, e.pageY);
        textNode = range.startContainer;
        offset = range.startOffset;
    }

    // only split TEXT_NODEs
    if (textNode.nodeType == 3) {
        var replacement = textNode.splitText(offset);
        var br = document.createElement('br');
        textNode.parentNode.insertBefore(br, replacement);
    }
}

var paragraphs = document.getElementsByTagName("p");
for (i=0 ; i < paragraphs.length; i++) {
    paragraphs[i].addEventListener("click", insertBreakAtPoint, false);
}

Specification

Specification Status Comment
{{ SpecName('CSSOM View', '#widl-Document-caretPositionFromPoint-CaretPosition-float-x-float-y', 'caretPositionFromPoint') }} {{ Spec2('CSSOM View') }}  

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox Internet Explorer Opera Safari
Basic support {{ CompatUnknown() }} {{ CompatGeckoDesktop("20.0") }} {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }}
Feature Android Firefox Mobile IE Phone Opera Mobile Safari Mobile
Basic support {{ CompatUnknown() }} {{ CompatGeckoMobile("20.0") }}
 
{{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }}

Gecko-specific notes

  • Offsets in {{HTMLElement("textarea")}} and {{HTMLElement("iframe")}} elements aren't correct - see {{bug("824965")}} and {{bug("826069")}} for details.

WebKit-specific notes

  • WebKit (Safari 5, Chrome) implements document.caretRangeFromPoint(x,y) from an older W3C draft. Also, note that a {{domxref("Range")}} is returned.

Trident-specific notes

  • For MS Internet Explorer the proprietary method TextRange.moveToPoint(x,y) might be helpful.

See also

  • {{domxref("CaretPosition")}}
  • {{domxref("Range")}}
  • {{domxref("Text")}}
  • {{domxref("Selection")}}
  • {{domxref("window.getSelection")}}

Revision Source

<h2 id="Summary" name="Summary">Summary</h2>
<p>This method is used to retrieve the caret position in a document based on two coordinates. A {{domxref("CaretPosition")}} is returned, containing the found DOM node and the character offset in that node.</p>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<pre class="eval">
var cp = document.caretPositionFromPoint(float x, float y);
</pre>
<h3 id="Parameters">Parameters</h3>
<dl>
  <dt>
    x</dt>
  <dd>
    Horizontal point on the page at where to determine the caret position.</dd>
  <dt>
    y</dt>
  <dd>
    Vertical point on the page at where to determine the caret position.</dd>
</dl>
<h3 id="Return_value">Return value</h3>
<p>A {{domxref("CaretPosition")}}. <code>Null</code>, if <strong>x</strong> or <strong>y</strong> are negative or greater than the viewport.</p>
<h2 id="Example" name="Example">Example</h2>
<p>Basic demo: When clicking in a paragraph insert a line break at the caret position:</p>
<pre class="brush: js">
function insertBreakAtPoint(e) {

&nbsp;&nbsp; &nbsp;var range;
&nbsp;&nbsp; &nbsp;var textNode;
&nbsp;&nbsp; &nbsp;var offset;

&nbsp;&nbsp; &nbsp;// standard
&nbsp;&nbsp; &nbsp;if (document.caretPositionFromPoint) {
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;range = document.caretPositionFromPoint(e.pageX, e.pageY);
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;textNode = range.offsetNode;
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;offset = range.offset;
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;
&nbsp;&nbsp; &nbsp;// WebKit
&nbsp;&nbsp; &nbsp;} else if (document.caretRangeFromPoint) {
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;range = document.caretRangeFromPoint(e.pageX, e.pageY);
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;textNode = range.startContainer;
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;offset = range.startOffset;
&nbsp;&nbsp; &nbsp;}

&nbsp;&nbsp; &nbsp;// only split TEXT_NODEs
&nbsp;&nbsp; &nbsp;if (textNode.nodeType == 3) {
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;var replacement = textNode.splitText(offset);
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;var br = document.createElement('br');
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;textNode.parentNode.insertBefore(br, replacement);
&nbsp;&nbsp; &nbsp;}
}

var paragraphs = document.getElementsByTagName("p");
for (i=0 ; i &lt; paragraphs.length; i++) {
&nbsp;&nbsp; &nbsp;paragraphs[i].addEventListener("click", insertBreakAtPoint, false);
}
</pre>
<h2 id="Specification" name="Specification">Specification</h2>
<table class="standard-table">
  <thead>
    <tr>
      <th scope="col">Specification</th>
      <th scope="col">Status</th>
      <th scope="col">Comment</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>{{ SpecName('CSSOM View', '#widl-Document-caretPositionFromPoint-CaretPosition-float-x-float-y', '<code>caretPositionFromPoint</code>') }}</td>
      <td>{{ Spec2('CSSOM View') }}</td>
      <td>&nbsp;</td>
    </tr>
  </tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Chrome</th>
        <th>Firefox</th>
        <th>Internet Explorer</th>
        <th>Opera</th>
        <th>Safari</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatGeckoDesktop("20.0") }}</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatUnknown() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<div id="compat-mobile">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Android</th>
        <th>Firefox Mobile</th>
        <th>IE&nbsp;Phone</th>
        <th>Opera Mobile</th>
        <th>Safari Mobile</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatGeckoMobile("20.0") }}<br />
          &nbsp;</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatUnknown() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<h3 id="Gecko-specific_notes">Gecko-specific notes</h3>
<ul>
  <li>Offsets in {{HTMLElement("textarea")}} and {{HTMLElement("iframe")}} elements aren't correct - see {{bug("824965")}} and {{bug("826069")}} for details.</li>
</ul>
<h3>WebKit-specific notes</h3>
<ul>
  <li>WebKit (Safari 5, Chrome) implements <code>document.caretRangeFromPoint(x,y)</code> from an <a href="http://www.w3.org/TR/2009/WD-cssom-view-20090804/#dom-documentview-caretrangefrompoint" title="http://www.w3.org/TR/2009/WD-cssom-view-20090804/#dom-documentview-caretrangefrompoint">older W3C draft</a>. Also, note that a {{domxref("Range")}} is returned.</li>
</ul>
<h3>Trident-specific notes</h3>
<ul>
  <li>For MS Internet Explorer the proprietary method <code>TextRange.moveToPoint(x,y)</code> might be helpful.</li>
</ul>
<h2 id="See_also">See also</h2>
<ul>
  <li>{{domxref("CaretPosition")}}</li>
  <li>{{domxref("Range")}}</li>
  <li>{{domxref("Text")}}</li>
  <li>{{domxref("Selection")}}</li>
  <li>{{domxref("window.getSelection")}}</li>
</ul>
Revert to this revision