Use await elementHandle.boundingBox() to get an element’s bounds. It returns a box relative to the main frame, or null if the element is not part of layout—for example, when it has display: none.
Get the bounding box
Wait for the element, check that Puppeteer found it, then check the nullable result before reading its coordinates or dimensions:
const element = await page.waitForSelector('.target');
if (!element) {
throw new Error('Target element was not found');
}
const box = await element.boundingBox();
if (!box) {
throw new Error('Target element has no layout box');
}
console.log(box.x, box.y, box.width, box.height);boundingBox() is an asynchronous ElementHandle method. Its documented return type is Promise<BoundingBox | null>. See the Puppeteer boundingBox() API reference.
What the returned coordinates mean
Puppeteer documents the bounding box as relative to the main frame. Do not assume from that description that the values are document coordinates or coordinates adjusted for page scrolling; the method reference does not specify either interpretation.
#1 Best Overall
If you are using the box for a mouse operation, Puppeteer describes page mouse coordinates as main-frame CSS pixels relative to the viewport’s upper-left corner. A page change between measuring and acting can affect the target, so measure close to the interaction and verify the page has not shifted. See the Puppeteer Mouse API reference.
Why boundingBox() returns null
A null result is not the same as a missing selector. The selector wait can fail to produce a handle; if it does produce one, boundingBox() can still return null when the element is not part of layout. Puppeteer gives an element styled with display: none as an example.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
- If
waitForSelector()returns no handle, check the selector and whether the element appears before the wait times out. - If
boundingBox()returnsnull, check whether the element participates in layout, including whether it or an ancestor is hidden withdisplay: none. - Always branch on the result before accessing
x,y,widthorheight.
Bounding box or element screenshot?
Use boundingBox() when you need geometry to inspect or use in a later step. If the goal is to capture the element itself, Puppeteer provides ElementHandle.screenshot() instead. Its guide says Puppeteer tries to scroll the element into view by default if it is hidden; that is screenshot behavior and does not change the nullable behavior of boundingBox(). See the Puppeteer screenshots guide.
Or skip the browser setup
If you need a page screenshot rather than element coordinates, ScreenshotNeo can return an image or PDF from one GET request. For example, using cURL:
Recommended Free Tools
Quick Recap
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
Rank #3
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for request options. It removes cookie banners, popups and chat widgets before the shot; bot checks, blank pages and failed loads are never billed. Its MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for free.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
