Element.getBoundingClientRect()

  • Revision slug: DOM/element.getBoundingClientRect
  • Revision title: element.getBoundingClientRect
  • Revision id: 13544
  • Created:
  • Creator: vmeurisse
  • Is current revision? No
  • Comment 2 words added, 1 words removed

Revision Content

{{ gecko_minversion_header("1.9") }} {{ DomRef() }}

Summary

Returns a text rectangle object that encloses a group of text rectangles.

Syntax

var rectObject = object.getBoundingClientRect();

Returns

The returned value is a TextRectangle object which is the union of the rectangles returned by getClientRects() for the element, i.e., the CSS border-boxes associated with the element.

The returned value is a TextRectangle object, which 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.

{{ gecko_callout_heading("1.9.1") }}

Firefox 3.5 adds width and height properties to the TextRectangle object.

Empty border-boxes are completely ignored. If all the element's border-boxes are empty, then a rectangle is returned with a width and height of zero and where the top and left are the top-left of the border-box for the first CSS box (in content order) for the element.

The amount of scrolling that has been done of the viewport area (or any other scrollable element) is taken into account when computing the bounding rectangle. This means that the top and left property change their values as soon as the scrolling position changes (so their values are relative to the viewport and not absolute). If this is not the desired behaviour just add the current scrolling position to the top and left property (via window.scrollX and window.scrollY) to get constant values independent from the current scrolling position.

{{ gecko_callout_heading("12.0") }}

Starting in Gecko 12.0 {{ geckoRelease("12.0") }}, the effect of CSS transforms is considered when computing the element's bounding rectangle.

For cross-browser compatibility, use window.pageXOffset and window.pageYOffset instead of window.scrollX and window.scrollY, except use (((t = document.documentElement) || (t = document.body.parentNode)) && typeof t.ScrollLeft == 'number' ? t : document.body).ScrollLeft and (((t = document.documentElement) || (t = document.body.parentNode)) && typeof t.ScrollTop == 'number' ? t : document.body).ScrollTop when window.pageXOffset and window.pageYOffset (and window.pageXOffset and window.pageYOffset) are undefined.

Example

var rect = obj.getBoundingClientRect();

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 1.0 {{ CompatGeckoDesktop("1") }} 4.0 {{ CompatVersionUnknown() }} 4.0
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support 2.0 1.0 {{ CompatGeckoMobile("1") }} 6.0 {{ CompatVersionUnknown() }} 4.0

 

Specification

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

Notes

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

References

  • {{ MSDN("ms536433", "getBoundingClientRect Method") }}

See also

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

Revision Source

<p>{{ gecko_minversion_header("1.9") }} {{ DomRef() }}</p>
<h3 id="Summary" name="Summary">Summary</h3>
<p>Returns a text rectangle object that encloses a group of text rectangles.</p>
<h3 id="Syntax" name="Syntax">Syntax</h3>
<pre class="eval">var <em>rectObject</em> = <var>object</var>.getBoundingClientRect();
</pre>
<h3 id="Returns" name="Returns">Returns</h3>
<p>The returned value is a <a href="/en/XPCOM_Interface_Reference/nsIDOMClientRect" title="en/nsIDOMClientRect">TextRectangle</a> object which is the union of the rectangles returned by <code>getClientRects()</code> for the element, i.e., the CSS border-boxes associated with the element.</p>
<p>The returned value is a <code>TextRectangle</code> object, which 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.</p>
<div class="geckoVersionNote"> <p>{{ gecko_callout_heading("1.9.1") }}</p> <p>Firefox 3.5 adds <code>width</code> and <code>height</code> properties to the <code>TextRectangle</code> object.</p>
</div>
<p>Empty border-boxes are completely ignored. If all the element's border-boxes are empty, then a rectangle is returned with a width and height of zero and where the <code>top</code> and <code>left</code> are the top-left of the border-box for the first CSS box (in content order) for the element.</p>
<p>The amount of scrolling that has been done of the viewport area (or any other scrollable element) is taken into account when computing the bounding rectangle. This means that the <code>top</code> and <code>left</code> property change their values as soon as the scrolling position changes (so their values are relative to the viewport and not absolute). If this is not the desired behaviour just add the current scrolling position to the <code>top</code> and <code>left</code> property (via <code>window.scrollX</code> and <code>window.scrollY</code>) to get constant values independent from the current scrolling position.</p>
<div class="geckoVersionNote" style="undefined"> <p>{{ gecko_callout_heading("12.0") }}</p> <p>Starting in Gecko 12.0 {{ geckoRelease("12.0") }}, the effect of <a href="/En/CSS/Using_CSS_transforms" title="Using CSS transforms">CSS transforms</a> is considered when computing the element's bounding rectangle.</p>
</div>
<p>For cross-browser compatibility, use <code>window.pageXOffset</code> and <code>window.pageYOffset</code> instead of <code style="color: inherit; font-weight: inherit; ">window.scrollX</code> and <code style="color: inherit; font-weight: inherit; ">window.scrollY</code>, except use <code>(((t = document.documentElement) || (t = document.body.parentNode)) &amp;&amp; typeof t.ScrollLeft == 'number' ? t : document.body).ScrollLeft</code> and <code>(((t = document.documentElement) || (t = document.body.parentNode)) &amp;&amp; typeof t.ScrollTop == 'number' ? t : document.body).ScrollTop</code> when <code style="color: inherit; font-weight: inherit; ">window.pageXOffset</code> and <code>window.pageYOffset (and </code><code style="color: inherit; font-weight: inherit; ">window.pageXOffset</code> and <code style="color: inherit; font-weight: inherit; ">window.pageYOffset</code><code>)</code> are undefined.</p>
<h3 id="Example" name="Example">Example</h3>
<pre class="eval">var rect = obj.getBoundingClientRect();
</pre>
<h3 id="Browser_compatibility">Browser compatibility</h3>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop"> <table class="compat-table"> <tbody> <tr> <th>Feature</th> <th>Chrome</th> <th>Firefox (Gecko)</th> <th>Internet Explorer</th> <th>Opera</th> <th>Safari</th> </tr> <tr> <td>Basic support</td> <td>1.0</td> <td>{{ CompatGeckoDesktop("1") }}</td> <td>4.0</td> <td>{{ CompatVersionUnknown() }}</td> <td>4.0</td> </tr> </tbody> </table>
</div>
<div id="compat-mobile"> <table class="compat-table"> <tbody> <tr> <th>Feature</th> <th>Android</th> <th>Chrome for Android</th> <th>Firefox Mobile (Gecko)</th> <th>IE Mobile</th> <th>Opera Mobile</th> <th>Safari Mobile</th> </tr> <tr> <td>Basic support</td> <td>2.0</td> <td>1.0</td> <td>{{ CompatGeckoMobile("1") }}</td> <td>6.0</td> <td>{{ CompatVersionUnknown() }}</td> <td>4.0</td> </tr> </tbody> </table>
</div>
<p> </p>
<h3 id="Specification" name="Specification">Specification</h3>
<p><a class="external" href="http://www.w3.org/TR/cssom-view/#the-getclientrects" title="http://www.w3.org/TR/cssom-view/#the-getclientrects">CSSOM Views: The getClientRects() and getBoundingClientRect() methods </a></p>
<h3 id="Notes" name="Notes">Notes</h3>
<p><code>getBoundingClientRect()</code> was first introduced in the MS IE DHTML object model.</p>
<h3 id="References" name="References">References</h3>
<ul> <li>{{ MSDN("ms536433", "getBoundingClientRect Method") }}</li>
</ul>
<h3 id="See_also">See also</h3>
<ul> <li><a class="internal" href="/en/DOM/element.getClientRects" title="En/DOM/Element.getClientRects"><code>getClientRects()</code></a></li>
</ul>
<p>{{ languages( { "es": "es/DOM/element.getBoundingClientRect", "fr": "fr/DOM/element.getBoundingClientRect", "ja": "ja/DOM/element.getBoundingClientRect" } ) }}</p>
Revert to this revision