Sizes, scrolling & coordinates

How big is a box, and where is it?

Web pages often ask questions about real space on the screen:

• How wide is this card?
• How far has this list scrolled?
• Where is this button on the screen?
• Which element is under the mouse pointer right now?

The browser already knows the answers. Before it draws a page, it works out the size and place of every element. This work is called layout. In this lesson you learn to read the browser's answers instead of guessing them.

The answers come in two groups:

• Sizes tell you how big an element's box is. The box has layers: the content, the padding around the content, and the border around the padding.
• Coordinates tell you where a box or a point is. A coordinate is a distance in pixels from a starting edge, such as the top of the screen.

Many layout bugs come from mixing up these two groups.

In the previous lesson, Styles & classes, you changed how elements look. Now you read the sizes and places that those styles produce. The Event loop lesson showed that the browser draws the page in steps. The same order helps here: change styles first, let the browser do layout, then read all your measurements together.

Every element has three groups of size properties. The first word of each name tells you which part of the box it measures:

• offsetWidth and offsetHeight measure the whole box: content, padding, and border. If the box has a scrollbar, they count it too. They are always whole numbers, and they ignore transforms. A transform is a CSS effect, such as transform: scale(1.5), that makes an element look bigger or smaller without changing the layout.
• clientWidth and clientHeight measure inside the border: content and padding. They leave out the border and any scrollbar. clientTop and clientLeft are usually the widths of the top and left borders.
• scrollWidth and scrollHeight measure all of the content, including the parts that stick out and are hidden. scrollTop and scrollLeft tell you how far the box has scrolled. You can also set them to scroll the box.

Try the playground below slowly:

1. Turn on the padding. Both the offset sizes and the client sizes grow.
2. Turn on the border. The offset sizes grow again, but the client sizes do not.
3. Turn on the overflow. scrollHeight grows, because the hidden content still counts.

const card = { offsetWidth: 220, clientWidth: 204, scrollWidth: 260 };
console.log(card.offsetWidth - card.clientWidth);
console.log(card.scrollWidth - card.clientWidth);

This small example uses numbers that were already measured, so it needs no real element.

• Line 2 takes the inside width away from the whole width: 220 − 204 prints 16. Those 16 pixels are the border, plus a scrollbar if there is one.
• Line 3 takes the inside width away from the width of all the content: 260 − 204 prints 56. Those 56 pixels of content stick out of view.

1const hiddenBelow = element.scrollHeight - element.scrollTop - element.clientHeight;2const atBottom = hiddenBelow <= 1;

Many pages need to know if a scrolling box has reached the bottom. For example, a chat app loads older messages, or a "Back to top" button appears. This code checks it:

1const hiddenBelow = element.scrollHeight - element.scrollTop - element.clientHeight;2const atBottom = hiddenBelow <= 1;

• Line 1 works out hiddenBelow: the number of pixels still hidden below the part you can see.
• Line 2 says the box is "at the bottom" when that number is 1 or less.

Why not check for exactly 0? Sizes on the screen can include parts of a pixel, such as 99.5. Some properties round them to whole numbers. So good code asks "Is it within one or two pixels?" instead of "Is it exactly equal?"

A scroll position has limits. It can go from 0 up to scrollHeight - clientHeight. If you set a bigger number, the browser uses the biggest allowed value instead. If you set a negative number, the browser uses 0. So after you set a scroll position, read it again to see where the box really is.

const maxScroll = 300 - 60;
console.log(Math.min(500, maxScroll));
console.log(Math.max(-20, 0));

This example copies what the browser does. Math.min picks the smaller of two numbers, and Math.max picks the bigger one.

• Line 1: the box has 300 pixels of content and shows 60 of them, so the biggest scroll position is 240.
• Line 2 asks for 500 and gets 240.
• Line 3 asks for -20 and gets 0.

Now step through the math one line at a time. The box has these measurements:

• scrollHeight is 300: the height of all the content.
• clientHeight is 100: the height you can see.
• scrollTop is 199: the box has scrolled 199 pixels down.

So 1 pixel is still hidden. Does that count as "at the bottom"? The tolerance is how many pixels you allow. Pick one, guess the answer, then step through.

1const box = { scrollTop: 199, clientHeight: 100, scrollHeight: 300 };Run2const hiddenBelow = box.scrollHeight - box.scrollTop - box.clientHeight;3const atBottom = hiddenBelow <= 2;4console.log(atBottom);

The viewport is the part of the page you can see in the browser window right now.

element.getBoundingClientRect() tells you where an element is in the viewport. It returns an object called a DOMRect, which holds these numbers:

• top and left: how far the element's top and left edges are from the top and left of the viewport.
• bottom and right: how far the element's bottom and right edges are from the top and left of the viewport.
• width and height: the size of the element's whole box, with content, padding, and border.

Because rect.top is measured from the viewport, it changes when you scroll the page.

The CSS width you write is not always the width you measure. It depends on the CSS box-sizing property:

• With content-box (the default), width sets only the content. The padding and border are added outside it.
• With border-box, width sets the whole box. The padding and border fit inside it.

const sizes = { cssWidth: 200, padding: 20, border: 4 };
const contentBox = sizes.cssWidth + sizes.padding * 2 + sizes.border * 2;
const borderBox = sizes.cssWidth;
const contentWidth = sizes.cssWidth - sizes.padding * 2 - sizes.border * 2;
console.log(contentBox, borderBox, contentWidth);

The example has a CSS width of 200, 20 pixels of padding on each side, and a 4-pixel border on each side.

• Line 2: with content-box, the outer width is 200 + 40 + 8 = 248.
• Line 3: with border-box, the outer width stays 200.
• Line 4: then the content gets only 200 − 40 − 8 = 152.

So the program prints 248 200 152. When CSS rules are involved, measure the real element. Don't work out its width from one line of CSS.

The rectangle can include parts of a pixel, and it includes transforms. Turn on the scale in the playground below. The width from getBoundingClientRect() changes with the scale, but offsetWidth keeps the layout width.

1const rect = target.getBoundingClientRect();2const pageTop = rect.top + window.scrollY;

There are two ways to measure a position. Viewport coordinates are measured from the top-left corner of what you can see. Document coordinates are measured from the top-left corner of the whole page. Mouse events give you both: event.clientX and event.clientY are viewport coordinates, and event.pageX and event.pageY are document coordinates.

The table below compares the two. Each row asks a question, then gives the answer for each kind of position.

Two methods scroll a box or the page:

• scrollTo moves to an exact position, such as the very top.
• scrollBy moves by an amount from where you are now, such as 80 pixels down.

Both work on elements and on window, the whole page. For example, window.scrollTo({ top: 0, behavior: "smooth" }) moves the page to the top. The option behavior: "smooth" makes it slide instead of jump. Only scroll the page when the reader asks, for example after they click a button. Moving the page by surprise is confusing.

element.scrollIntoView() is often easier. It asks the browser to scroll until that element can be seen. The option block: "nearest" means "move as little as needed." That works well when a scrolling box sits inside a scrolling page.

1list.scrollBy({ top: 80, behavior: "smooth" });2item.scrollIntoView({ behavior: "smooth", block: "nearest" });

const innerWidth = 1024;
const clientWidth = 1007;
console.log(innerWidth - clientWidth);

In this example, the difference is 17 pixels. Some computers draw the scrollbar on top of the page instead of beside it. Then the difference is smaller, or 0. So measure it; don't assume 17.

When the reader scrolls, the browser fires a scroll event, often many times a second. Heavy work in every event can make the page stutter.

There is one problem to watch for. Suppose each event changes a style, then reads a size, then changes a style, then reads again. Each read after a change makes the browser redo its layout at once. Doing this again and again is called layout thrashing. To avoid it:

• Do all your reads together.
• Then do all your writes together.
• Use requestAnimationFrame for changes on the screen. It runs your function once, just before the browser draws the next frame (the next picture of the page).

1let ticking = false;2box.addEventListener("scroll", () => {3  if (!ticking) {4    requestAnimationFrame(updateReadout);5    ticking = true;6  }7}, { passive: true });

Add { passive: true } to a scroll listener when it never calls preventDefault(). This tells the browser that your listener won't stop the scroll, so the browser can scroll without waiting for it.

To find out when a card comes into view, use IntersectionObserver instead. The later Observers lesson covers it. Newer browsers also have a scrollend event, which fires once when scrolling stops. Before you use it, check that the browser has it with "onscrollend" in document.

document.elementFromPoint(x, y) asks the browser: "Which element is on top at this point of the viewport?" It uses viewport coordinates, the same kind as clientX and clientY from mouse events. If the point is outside the viewport, it returns null.

Finding the element under a point is called hit testing. Drag-and-drop tools and page inspectors use it.

1area.addEventListener("pointermove", (event) => {2  const hit = document.elementFromPoint(event.clientX, event.clientY);3});

Where you’ll use this

You will meet these measurements in everyday pages:

• A tooltip (a small pop-up label) reads its button's rectangle and places itself next to the button.
• A chat app checks if the message list is near the bottom before it scrolls to a new message.
• A very long list draws only the rows you can see. It uses clientHeight and scrollTop to pick them.
• A drawing tool uses elementFromPoint to find the shape under the pointer.

1const rect = button.getBoundingClientRect();2const top = rect.bottom + window.scrollY;3const left = rect.left + window.scrollX;4 5tooltip.style.transform = `translate(${left}px, ${top}px)`;

• Line 1 reads the button's rectangle in the viewport.
• Lines 2 and 3 add the scroll amounts to get positions on the whole page.
• Line 5 moves the tooltip there with one style change.

This code needs real elements, so it doesn't run here. The next example does the same math with numbers.

const button = { bottom: 120, left: 40 };
const page = { scrollX: 10, scrollY: 300 };
console.log(button.left + page.scrollX, button.bottom + page.scrollY);

• The button's bottom is 120 pixels below the top of the viewport, and the page has scrolled 300 pixels down. So on the whole page, the tooltip's top is 120 + 300 = 420.
• The button's left edge is 40 pixels from the left of the viewport, and the page has scrolled 10 pixels sideways. So on the whole page, its left is 40 + 10 = 50.

Line 3 prints 50 420.

const card = { top: -20, right: 300, bottom: 80, left: 40 };
const viewport = { width: 800, height: 600 };
const inView = card.bottom > 0 && card.right > 0 && card.top < viewport.height && card.left < viewport.width;
console.log(inView);

Line 3 checks four things. The card is in view only if all four are true:

• Its bottom is below the top edge of the viewport: card.bottom > 0.
• Its right edge is past the left edge of the viewport: card.right > 0.
• Its top is above the bottom edge of the viewport: card.top < viewport.height.
• Its left edge is before the right edge of the viewport: card.left < viewport.width.

This card starts 20 pixels above the viewport, but its bottom is 80 pixels below the top edge. So part of it can still be seen, and the program prints true. If you checked only the top, you would hide a card that is still partly on the screen.

Notice the order in the tooltip code: read the rectangle, work out the page position, then make one style change. If you need several measurements, read them all first. Then change the classes or styles. That stops the browser from redoing layout again and again.

Misconceptions and edge cases

• "offsetWidth and getBoundingClientRect().width are the same." Not always. offsetWidth is a whole number and ignores transforms. getBoundingClientRect() can include parts of a pixel, and it includes transforms.
• "clientWidth is the content width." It also includes the padding. It leaves out the border and any scrollbar.
• "rect.top is a fixed place on the page." It is measured from the viewport, so it changes when you scroll. Add scrollY to get the place on the whole page.
• "Reading sizes costs nothing." A read right after a style change can make the browser redo layout at once. Do the reads together, then the writes together.
• "Hidden elements still have a size." An element with display: none takes up no space. Its sizes are 0, and its offsetParent is null. offsetParent is the parent element that offsetTop and offsetLeft are measured from.
• "elementFromPoint uses pageX and pageY." It uses viewport coordinates. Pass it clientX and clientY.

Key takeaways

• offsetWidth and offsetHeight measure the whole box with its border, as whole numbers. They ignore transforms.
• clientWidth and clientHeight measure inside the border. scrollWidth and scrollHeight measure all the content, even the hidden part.
• getBoundingClientRect() tells you where the box is in the viewport. It can include parts of a pixel, and it includes transforms.
• A position on the whole page = a position in the viewport + scrollX or scrollY.
• Do layout reads together and writes together. Update the screen once per frame with requestAnimationFrame.
• elementFromPoint takes viewport coordinates and returns the element on top at that point.

Sizes tell you how big a box is. Coordinates tell you where a box or a point is, measured from the viewport or from the whole page.

Up next: Selection & Range.