CKTIS / JavaScript
Element.getBoundingClientRect(): DOMRect dimensions and position
Measure an element’s bounding rectangle in CSS pixels and distinguish viewport-relative coordinates from document coordinates.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
const rect = element.getBoundingClientRect();
const { x, y, width, height, top, right, bottom, left } = rect;element.getBoundingClientRect() takes no arguments and returns a DOMRect. It is a Web API, not part of ECMAScript. Measuring an element requires a runtime with DOM layout support; availability depends on the runtime.
For an HTML element, the measurement is based on axis-aligned rectangles for its CSS border boxes. It includes padding and borders, accounts for CSS transforms, and excludes margins. Use getClientRects() to get the individual rectangles. If the list is empty, as with display: none, all values are zero. If every rectangle has zero width or zero height, the method returns the first rectangle in the list. Otherwise, it returns the smallest rectangle enclosing all rectangles in the list except those with both dimensions zero. For an inline element spanning multiple lines, the result can cover gaps between fragments. The rectangle alone does not prove the element is visible.
width and height are the rectangle’s dimensions. In this result, x and y equal left and top; right is left + width and bottom is top + height. Coordinates are measured from the viewport’s top-left corner, not from its nearest edge, so they can be negative. All values are in CSS pixels and can be fractional.
On a DOMRect, x, y, width, and height are writable; the edge properties are derived and read-only. A manually created rectangle with negative width or height can have x different from left or y different from top. Editing the result does not change the element. The result is a snapshot, not a live measurement: call the method again after layout changes or scrolling if you need current values.
For the top-left corner in document coordinates, use rect.left + window.scrollX and rect.top + window.scrollY, reading the offsets when you measure. This changes the coordinate origin; it does not undo scrolling inside a nested container.
Examples
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Measuring an element</title>
</head>
<body>
<script>
(() => {
const box = document.createElement('div');
box.style.cssText = 'position: fixed; left: 24.5px; top: 16px; margin: 0; box-sizing: content-box; width: 104px; height: 44px; padding: 8px; border: 0;';
document.body.append(box);
try {
const rect = box.getBoundingClientRect();
const { x, y, width, height, top, right, bottom, left } = rect;
console.log(`x=${x}, y=${y}, width=${width}, height=${height}, top=${top}, right=${right}, bottom=${bottom}, left=${left}`);
box.style.left = '44.5px';
console.log(`previous x=${rect.x}, current x=${box.getBoundingClientRect().x}`);
} finally {
box.remove();
}
})();
</script>
</body>
</html>Result
x=24.5, y=16, width=120, height=60, top=16, right=144.5, bottom=76, left=24.5 previous x=24.5, current x=44.5
Save the example as an HTML file, open it in a browser, and read the output in the developer console. The dimensions include padding on both sides of each axis; the element has no border. After the element moves, the previous rectangle keeps its original `x`; only a fresh measurement gives the new `x`.
Related lessons
- JavaScript · Lesson 12 · Advanced · Version: 4