JavaScript Element getBoundingClientRect() Method

What You’ll Learn

Element.getBoundingClientRect() is an instance method that returns a DOMRect describing an element’s size and position relative to the viewport. Learn top, left, width, height, how scrolling changes values, document coordinates, and five try-it labs aligned with MDN.

Introduction

When you build tooltips, sticky headers, drag-and-drop UIs, or scroll-spy navigation, you often need to know where an element sits on screen and how big it is. getBoundingClientRect() answers both questions in one call.

It returns a DOMRect with pixel values for top, left, right, bottom, x, y, width, and height. Positions are relative to the viewport, not the whole document.

This page is part of JavaScript Element. Pair it with checkVisibility() when you need visibility checks too.

Understanding the getBoundingClientRect() Method

Calling el.getBoundingClientRect() measures the smallest rectangle that contains the entire element’s border box and returns it as a DOMRect.

• It is an instance method on Element.
• Takes no parameters (MDN).
• Returns a DOMRect with size and viewport-relative position.
• width / height include padding and border-width.
• Scrolling updates top, left, right, bottom.
• Related: getClientRects() for per-line boxes (MDN).

📝 Syntax

General form of Element.getBoundingClientRect (MDN):

getBoundingClientRect()

Parameters

None.

Return value

A DOMRect object. Its left, top, right, bottom, x, and y are distances from the viewport edges in pixels. width and height describe the border box size.

Common patterns

const box = element.getBoundingClientRect();

console.log(box.width, box.height);
console.log(box.top, box.left);

// Document coordinates (MDN):
const docTop = box.top + window.scrollY;
const docLeft = box.left + window.scrollX;

// Center point for tooltips:
const centerX = box.left + box.width / 2;
const centerY = box.top + box.height / 2;

Examples Gallery

Examples follow MDN Element.getBoundingClientRect() patterns. Use View Output or Try It Yourself for each case.

const box = document.querySelector(".demo-box");
const rect = box.getBoundingClientRect();

console.log(rect.width);   // includes padding + border
console.log(rect.height);
console.log(rect.top);     // distance from viewport top
console.log(rect.left);    // distance from viewport left

440
240
(varies by viewport)
(varies by viewport)

const box = document.getElementById("example");
const rect = box.getBoundingClientRect();

console.log(rect.top);
// Smaller number as you scroll down the page

Updates on scroll (viewport-relative)

const rect = element.getBoundingClientRect();

const docTop = rect.top + window.scrollY;
const docLeft = rect.left + window.scrollX;

console.log(docTop, docLeft);
// Stable while scrolling

Document top/left (scroll-independent)

const rect = button.getBoundingClientRect();

const centerX = rect.left + rect.width / 2;
const centerY = rect.top + rect.height / 2;

tooltip.style.left = `${centerX}px`;
tooltip.style.top = `${centerY - 8}px`;

Tooltip centered above button

const rect = element.getBoundingClientRect();
const vh = window.innerHeight;
const vw = window.innerWidth;

const inView =
  rect.bottom > 0 &&
  rect.right > 0 &&
  rect.top < vh &&
  rect.left < vw;

console.log(inView);

true or false

🚀 Common Use Cases

• Positioning tooltips, popovers, and context menus near a trigger element.
• Scroll-spy navigation that highlights the section currently in view.
• Drag-and-drop hit testing and drop-zone detection.
• Lazy-loading images when they enter the viewport.
• Measuring carousel slides or grid items for animations.
• Converting viewport coordinates to document coordinates for layout math.

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available, July 2015).
• Coordinates are viewport-relative; they change when the page scrolls.
• Includes padding and border (border box), not margin.
• For document position: rect.top + window.scrollY (MDN).
• Wrapped inline text may need getClientRects() instead.
• Related: checkVisibility(), closest(), JavaScript hub.

💡 Best Practices