Document.caretPositionFromPoint()

  • Revision slug: Web/API/document.caretPositionFromPoint
  • Revision title: document.caretPositionFromPoint
  • Revision id: 471923
  • Created:
  • Creator: Cobra
  • 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:

HTML Content

<p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum.
Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.</p>

JavaScript Content

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);
}

Demo

{{ EmbedLiveSample('Example', '100%', '300px') }}

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 {{ CompatNo() }}
See below
{{ CompatGeckoDesktop("20.0") }} {{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}
See below.
Feature Android Firefox Mobile IE Phone Opera Mobile Safari Mobile
Basic support {{ CompatNo() }} {{ CompatGeckoMobile("20.0") }}
 
{{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}

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>
<h3 id="HTML_Content">HTML Content</h3>
<pre class="brush: html">
&lt;p&gt;Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum.
Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.&lt;/p&gt;</pre>
<h3 id="JavaScript_Content">JavaScript Content</h3>
<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>
<h3 id="Demo">Demo</h3>
<p>{{ EmbedLiveSample('Example', '100%', '300px') }}</p>
<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>{{ CompatNo() }}<br />
          See below</td>
        <td>{{ CompatGeckoDesktop("20.0") }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}<br />
          See below.</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>{{ CompatNo() }}</td>
        <td>{{ CompatGeckoMobile("20.0") }}<br />
          &nbsp;</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</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 id="WebKit-specific_notes">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 id="Trident-specific_notes">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