Element.getClientRects()

  • Revision slug: DOM/element.getClientRects
  • Revision title: element.getClientRects
  • Revision id: 60680
  • Created:
  • Creator: yonathan
  • Is current revision? No
  • Comment (removed editor artifacts); 22 words removed

Revision Content

{{ Fx_minversion_header("3") }} {{ DomRef() }}

Summary

Returns a collection of rectangles that indicate the bounding rectangles for each box in a client.

Syntax

var rectCollection = object.getClientRects();

Returns

The returned value is a collection of ClientRect objects, one for each CSS border box associated with the element. Each ClientRect object contains read-only left, top, right and bottom properties describing the border box, in pixels, with the top-left relative to the top-left of the viewport, unless the element is inside an SVG foreignobject element, in which case the top-left is relative to the nearest foreignobject ancestor and in the coordinate system of that foreignobject. For tables with captions, the caption is included even though it's outside the border box of the table.

Originally, Microsoft intended this method to return a TextRectangle object for each line of text. However, the CSSOM working draft specifies that it returns a ClientRect for each border box. For an inline element, the two definitions are the same. But for a block element, Mozilla will return only a single rectangle.

{{ fx_minversion_note("3") }}

The amount of scrolling that has been done of the viewport area is taken into account when computing the rectangles.

The returned rectangles do not include the bounds of any child elements that might happen to overflow.

For HTML AREA elements, SVG elements that do not render anything themselves, display:none elements, and generally any elements that are not directly rendered, an empty list is returned.

Rectangles are returned even for CSS boxes that have empty border-boxes. The left, top, right and bottom coordinates can still be meaningful.

Fractional pixel offsets are possible.

Example

A paragraph with a span inside. Both the span and the paragraph have a border set. The client rects are in red:

paragraph-rects.png

A table with a caption. The client rects are in red:

table-rects.png

function addClientRectsOverlay(elt) {
  // Absolutely position a div over each client rect so that its border width
  // is the same as the rectangle's width.
// Note: the overlays will be out of place if the user resizes or zooms.
  var rects = elt.getClientRects();
  for (var i = 0; i != rects.length; i++) {
    var rect = rects[i];
    var tableRectDiv = document.createElement('div');
    tableRectDiv.style.position = 'absolute';
    tableRectDiv.style.border = '1px solid red';
    var scrollTop = document.documentElement.scrollTop ||
                    document.body.scrollTop;
    var scrollLeft = document.documentElement.scrollLeft ||
                    document.body.scrollLeft;
    tableRectDiv.style.margin = tableRectDiv.style.padding = '0';
    tableRectDiv.style.top = (rect.top + scrollTop) + 'px';
    tableRectDiv.style.left = (rect.left + scrollLeft) + 'px';
    // we want rect.width to be the border width, so content width is 2px less.
    tableRectDiv.style.width = (rect.width - 2) + 'px';
    tableRectDiv.style.height = (rect.height - 2) + 'px';
    document.body.appendChild(tableRectDiv);
  }
}

Specification

CSSOM Views: The getClientRects() and getBoundingClientRect() methods

Notes

getClientRects() was first introduced in the MS IE DHTML object model.

References

  • {{ MSDN("ms536435", "getClientRects Method") }}

See also

{{ languages( { "es": "es/DOM/element.getClientRects", "fr": "fr/DOM/element.getClientRects", "ja": "ja/DOM/element.getClientRects" } ) }}

Revision Source

<p>{{ Fx_minversion_header("3") }} {{ DomRef() }}</p>
<h3 name="Summary">Summary</h3>
<p>Returns a collection of rectangles that indicate the bounding rectangles for each box in a client.</p>
<h3 name="Syntax">Syntax</h3>
<pre class="eval">var <em>rectCollection</em> = <var>object</var>.getClientRects();
</pre>
<h3 name="Returns">Returns</h3>
<p>The returned value is a collection of ClientRect objects, one for each CSS border box associated with the element. Each ClientRect object contains read-only <code>left</code>, <code>top</code>, <code>right</code> and <code>bottom</code> properties describing the border box, in pixels, with the top-left relative to the top-left of the viewport, unless the element is inside an SVG <code>foreignobject</code> element, in which case the top-left is relative to the nearest <code>foreignobject</code> ancestor and in the coordinate system of that <code>foreignobject</code>. For tables with captions, the caption is included even though it's outside the border box of the table.</p>
<p>Originally, Microsoft intended this method to return a TextRectangle object for each <em>line</em> of text. However, the CSSOM working draft specifies that it returns a ClientRect for each <em>border box</em>. For an inline element, the two definitions are the same. But for a block element, Mozilla will return only a single rectangle.</p>
<p>{{ fx_minversion_note("3") }}</p>
<p>The amount of scrolling that has been done of the viewport area is taken into account when computing the rectangles.</p>
<p>The returned rectangles do not include the bounds of any child elements that might happen to overflow.</p>
<p>For HTML AREA elements, SVG elements that do not render anything themselves, <code>display:none</code> elements, and generally any elements that are not directly rendered, an empty list is returned.</p>
<p>Rectangles are returned even for CSS boxes that have empty border-boxes. The <code>left</code>, <code>top</code>, <code>right</code> and <code>bottom</code> coordinates can still be meaningful.</p>
<p>Fractional pixel offsets are possible.</p>
<h3 name="Example">Example</h3>
<p>A paragraph with a span inside. Both the span and the paragraph have a border set. The client rects are in red:</p>
<p><img alt="paragraph-rects.png" class="internal default" src="/@api/deki/files/4664/=paragraph-rects.png"></p>
<p>A table with a caption. The client rects are in red:</p>
<p><img alt="table-rects.png" class="internal default" src="/@api/deki/files/4665/=table-rects.png"></p>
<pre class="eval"><div><div>function addClientRectsOverlay(elt) {</div></div><div>  // Absolutely position a div over each client rect so that its border width</div><div>  // is the same as the rectangle's width.</div><div>// Note: the overlays will be out of place if the user resizes or zooms.</div><div>  var rects = elt.getClientRects();</div><div>  for (var i = 0; i != rects.length; i++) {</div><div>    var rect = rects[i];</div><div>    var tableRectDiv = document.createElement('div');</div><div>    tableRectDiv.style.position = 'absolute';</div><div>    tableRectDiv.style.border = '1px solid red';</div><div>    var scrollTop = document.documentElement.scrollTop ||</div><div>                    document.body.scrollTop;</div><div>    var scrollLeft = document.documentElement.scrollLeft ||</div><div>                    document.body.scrollLeft;</div><div>    tableRectDiv.style.margin = tableRectDiv.style.padding = '0';</div><div>    tableRectDiv.style.top = (rect.top + scrollTop) + 'px';</div><div>    tableRectDiv.style.left = (rect.left + scrollLeft) + 'px';</div><div>    // we want rect.width to be the border width, so content width is 2px less.</div><div>    tableRectDiv.style.width = (rect.width - 2) + 'px';</div><div>    tableRectDiv.style.height = (rect.height - 2) + 'px';</div><div>    document.body.appendChild(tableRectDiv);</div><div>  }</div><div>}</div></pre>
<h3 name="Specification">Specification</h3>
<p><a class="external" href="http://www.w3.org/TR/cssom-view/#the-getclientrects-and-getboundingclient" rel="external nofollow" target="_blank" title="http://www.w3.org/TR/cssom-view/#the-getclientrects-and-getboundingclient">CSSOM Views: The getClientRects() and getBoundingClientRect() methods </a></p>
<h3 name="Notes">Notes</h3>
<p><code>getClientRects()</code> was first introduced in the MS IE DHTML object model.</p>
<h3 name="References">References</h3>
<ul> <li>{{ MSDN("ms536435", "getClientRects Method") }}</li>
</ul>
<h3>See also</h3>
<ul> <li><a class="internal" href="/en/DOM/element.getBoundingClientRect" title="En/DOM/Element.getBoundingClientRect"><code>getBoundingClientRect()</code></a></li>
</ul>
<p>{{ languages( { "es": "es/DOM/element.getClientRects", "fr": "fr/DOM/element.getClientRects", "ja": "ja/DOM/element.getClientRects" } ) }}</p>
Revert to this revision