Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

Element bounding rectangles and client offsets

Measure an element’s position and size relative to the viewport, and distinguish those measurements from the left and top offsets of its client area.

Version: ECMAScript 2024 and the current web platform; runtime support varies

Syntax

element.getBoundingClientRect() // DOMRect
 element.clientLeft // integer Number
 element.clientTop // integer Number

Element.getBoundingClientRect/clientLeft/clientTop groups one method and two properties of Element. Call element.getBoundingClientRect() with no arguments for a DOMRect based on the transformed border-box rectangles from getClientRects(). If the list is empty, all values are zero. If every rectangle in the list has zero width or zero height, the method returns the first rectangle in the list. Otherwise, it returns the smallest axis-aligned rectangle enclosing the rectangles with a nonzero width or height. The measurement includes padding and borders, not margins. left and top are coordinates relative to the viewport’s top-left corner; width and height are dimensions. Values are in CSS pixels and can be fractional.

Read element.clientLeft and element.clientTop without parentheses. These read-only properties give integer offsets in CSS pixels, ignoring transforms: the left and top border thicknesses, respectively, plus any space taken up by a scrollbar on that same side. A vertical scrollbar can be on the left, for example in a right-to-left layout. Neither offset includes padding or margin. Both are zero for an inline box or when there is no CSS box.

The DOMRect is a snapshot. Measure again after scrolling or layout changes if you need current coordinates. To express left and top in document coordinates, add window.scrollX and window.scrollY, respectively. Don’t treat clientLeft and clientTop as viewport coordinates or as a general coordinate conversion after a transform. These are web platform APIs (CSSOM View), not ECMAScript 2024 features; availability depends on the runtime.

Examples

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Element geometry</title>
</head>
<body>
<script>
(() => {
  // Use a 1:1 ratio so the borders need no device-pixel rounding.
  if (window.devicePixelRatio !== 1) {
    throw new Error('Run at 100% page zoom with devicePixelRatio set to 1.');
  }

  const box = document.createElement('div');
  box.style.cssText = `
    position: fixed; left: 20px; top: 30px;
    box-sizing: border-box; width: 80px; height: 40px;
    border: solid black; border-width: 5px 2px 2px 3px;
    overflow: hidden; transform-origin: top left; transform: scale(2);
  `;
  document.body.append(box);
  try {
    const { left, top, width, height } = box.getBoundingClientRect();
    console.log(`rect: ${left}, ${top}, ${width}, ${height}`);
    console.log(`client: ${box.clientLeft}, ${box.clientTop}`);
  } finally {
    box.remove();
  }
})();
</script>
</body>
</html>

Result

rect: 20, 30, 160, 80
client: 3, 5

Open the HTML document in a browser at 100% page zoom with `devicePixelRatio` set to `1`. Read the output in the browser console. Scaling doubles the rectangle’s dimensions without moving its top-left corner; the client offsets remain `3` and `5`.

Related lessons

  • JavaScript · Lesson 35 · Advanced · Version: 4

Sources