This page is Ready to Use

Notice: The WebPlatform project, supported by various stewards between 2012 and 2015, has been discontinued. This site is now available on github.

getBoundingClientRect

Summary

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

Method of dom/HTMLElementdom/HTMLElement

Syntax

var rect = object.getBoundingClientRect();

Return Value

Returns an object of type ClientRectClientRect

ClientRect

 top: Number
 left: Number
 right: Number
 bottom: Number
 width: Number
 height: Number

Examples

This example uses the getClientRects and getBoundingClientRect methods to highlight text lines in an object.

<HEAD>
<SCRIPT>
var rcts;
var keyCount=0;
function Highlight(obj) {
    rcts = obj.getClientRects();
    rctLength= rcts.length;
    if (keyCount > rctLength-1) {
        idBeige.style.display="none";
        keyCount = 0
    }
    // set the rendering properties for the yellow DIV
    cdRight = rcts[keyCount].right + idBody.scrollLeft;
    cdLeft = rcts[keyCount].left + idBody.scrollLeft;
    cdTop = rcts[keyCount].top + idBody.scrollTop;
    cdBottom = rcts[keyCount].bottom + idBody.scrollTop;
    idYellow.style.top = cdTop;
    idYellow.style.width = (cdRight-cdLeft) - 5;
    idYellow.style.display = 'inline';
    // set the rendering properties for the beige DIV
    bndRight = obj.getBoundingClientRect().right +
        idBody.scrollLeft;
    bndLeft = obj.getBoundingClientRect().left +
        idBody.scrollLeft;
    bndTop = obj.getBoundingClientRect().top +
        idBody.scrollTop;
    idBeige.style.top = bndTop;
    idBeige.style.width = (bndRight-bndLeft) - 5;
    idBeige.style.height = cdTop - bndTop;
    if (keyCount>0){
        idBeige.style.display = 'inline';
    }
    keyCount++;
}
</SCRIPT>
</HEAD>
<BODY ID="idBody">
<DIV ID="oID_1" onclick="Highlight(this)"
    onkeydown="Highlight(this)">
A large block of text should go here. Click this
block of text multiple times to see each line
highlight with every click of the mouse button.
Once each line has been highlighted, the process
begins again starting with the first line.
</DIV>
<DIV STYLE="position:absolute; left:5; top:400;
z-index:-1; background-color:yellow; display:none"
ID="idYellow"></DIV>
<DIV STYLE="position:absolute; left:5; top:400;
z-index:-1; background-color:beige; display:none"
ID="idBeige"></DIV>
</BODY>

View live example

This example uses the ClientRect collection with the getClientRects and getBoundingClientRect methods to determine the position of the text rectangle within an element. In each line, the left-justified text does not extend to the right margin of the box that contains the text. Using the collection, you can determine the coordinates of the rectangle that surrounds only the content in each line. The example code reads these rectangle coordinates and instructs the ball to move over the text only, and not to the end of the line.

<HEAD>
<SCRIPT>
var timid = -1;
var timoID_2 = -1;
var nLine;
var nPosInLine;
var oRcts;
var nDivLen;
var nEraser;
function LoadDone() {
    oTextRange = document.body.createTextRange();
    // Get bounding rect of the range
    oRcts = oTextRange.getClientRects();
    nLine = 0;
    oBndRct = obj.getBoundingClientRect();
    nDivLen = oBndRct.right - oBndRct.left + 1;
    MoveTo();
}
function MoveTo() {
    if (nLine >= oRcts.length) {
        nLine = 0;
    }
    obj.style.top = oRcts[nLine].top;
    nPosInLine = oRcts[nLine].left;
    nEraser = 0;
    timoID_2 = setInterval("MoveToInLine()",60);
}
function MoveToInLine() {
    if (nPosInLine >= oRcts[nLine].right - nDivLen) {
        clearInterval(timoID_2);
        timoID_2 = -1;
        obj.style.left = oRcts[nLine].right - nDivLen;
        nLine++;
        timid = setTimeout("MoveTo()", 100);
        return;
    }
    if (nEraser == 0) {
        nEraser = 1;
    }
    else {
        nEraser = 0;
    }
    im.src = "/workshop/graphics/dot.png";
    obj.style.left = nPosInLine;
    nPosInLine += 3;
}
function End() {
    if(timid != -1) {
        clearInterval(timid);
        timid = -1;
    }
    if(timoID_2 != -1) {
        clearInterval(timoID_2);
        timoID_2 = -1;
    }
}
</SCRIPT>
</HEAD>
<BODY ID="bodyid" onload="LoadDone()"
    onresize="End();LoadDone();" onunload="End()">
<P STYLE="text-align:center">
<B>The quick brown fox jumps over the lazy dog.</B>
</P>
<DIV ID="obj" STYLE="position:absolute">
<IMG ID="im" SRC="/workshop/graphics/dot.png"
    BORDER=0 HEIGHT=16 WIDTH=16>
</DIV>
</BODY>

View live example

Usage

 The returned value is a ClientRect object which is the union of the rectangles returned by getClientRects() for the element, i.e., the CSS border-boxes associated with the element. It 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.

Essentially, the browser calculates all rectangles (see below getClientRects()), and getBoundingClientRect() returns the lowest (top, left) or highest (bottom, right) values found.

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.

Notes

Compatibility notes

Internet Explorer 8 and below - getBoundingClientRect returns a proprietary TextRectangle object. While it is similar to ClientRect, it does not have height or width properties and furthermore cannot have any additional properties (including height and width) added to it.

Related specifications

CSSOM View Module
Working Draft

Attributions