Tutorial

Using getBoundingClientRect to Get an Element's Size and Position

Updated on August 19, 2020

JavaScript

Using getBoundingClientRect to Get an Element's Size and Position

Introduction

getBoundingClientRect, part of the JavaScript DOM (Document Object Model), provides you with important pieces of data about an HTML element’s size and positioning.

In this article, you will use getBoundingClientRect to get an element’s size and position.

Prerequisites

To complete this tutorial, you should be familiar with the following concepts:

How to Add JavaSCript to HTML
How To Access Elements in the DOM
Working with Objects in JavaScript, which you can explore by reading Understainding Objects in JavaScript.

Understanding `getBoundingClientRect()`

To use getBoundingClientRect, first fetch an HTML element and call getBoundingClientRect on the element:

document.getElementById("foo").getBoundingClientRect();

getBoundingClientRect returns an object with several key/value pairs that give you information on the element’s size and positioning within the webpage.

Output
{
  top: 450,
  left: 400,
  right: 825,
  bottom: 500,
  x: 400,  
  y: 450,  
  width: 425,
  height: 50
}

The following illustration describes the information that is returned for each value:

Illustrative example 1

The x and y values will be equivalent to the left and top values. Because of this, some browsers omit x and y and only return left and top.

Another thing to notice is that right/bottom may be different than you are accustomed to in CSS positioning, like when positioning using position: absolute.

Here’s an illustration that shows the values and how they relate to the element:

Illustrative example 2

Now that you have seen what getBoundingClientRect() returns, use the same example to see if you understand the output from getBoundingClientRect().

Using `getBoundingClientRect` in an Application

To use getBoundingClientRect in your own code, you’ll need an HTML document with an element you want to query.

Create a new HTML file called boundingbox.html in your text editor:

nano boundingbox.html`

In the file, create an HTML document that contains a <div> tag in the <body> with the id of hello"

boundingbox.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>useBoundingBox example</title>
  </head>
  <body>
    <div id="hello">Hello World</div>
  </body>
</html>

Once you have an element on the page you can call getBoundingClientRect on the #foo element. Below the closing <body> tag, add a new <script> tag. Inside the <script> tag, fetch the element with the id of hello and call getBoundingClientRect(). Print the results to the JavaScript console:

boundingbox.html

<body>
  <div id="hello">Hello World</div>

  <script>
  const helloElement = document.getElementById('hello');
  const results = helloElement.getBoundingClientRect();
  </script>

</body>

Save the file and load boundingbox.html in your browser.

The console shows this output:

Outputbottom: 27.199996948242188
height: 19.199996948242188
left: 8
right: 1261
top: 8
width: 1253
x: 8
y: 8

The output from the #hello element shows you the size and position of it on the webpage. You can use this information to position other elements relative to this one, animate elements, and more.

Conclusion

In this article, you saw that getBoundingClientRect provides a rich amount of data about an element’s position. Since getBoundingClientRect is relative to the viewport, you can add window.scrollY and window.scrollX values to the top and left fields to get the HTML element’s position relative to the entire webpage.

It is reliably supported on all desktop and mobile browsers, with the exclusion of the x and y values which is unstable in older versions of Internet Explorer/Edge and Safari.

For even more detailed information about getBoundingClientRect you can read the official specification from the W3C’s CSS Object Model (CSSOM) View Module.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about our products

About the authors