completefrontend
Open lab My progress
THE WEB PERFORMANCE FIELD GUIDE

What causes layout shifts

Trace each layout shift to its cause: images and video without a size, ads in iframes, injected content, web fonts, and animated top, left, width or height.

By the end, you can
  • 01
    Trace a shift back to its causeRead what Chrome says moved, and find what above or beside it made room.
  • 02
    Explain the four loading causesSay why media without a size, ads, added content and web fonts push a page, and by how much.
  • 03
    Tell which animations shift the pageKnow that top, left, width and height make a shift in every frame, and that transform makes none.

Three jumps on Ravi's new page

Ravi has rebuilt the Leaf and Kettle's mint tea page. It has a photo of the tea now. The brewing steps are in Caveat, the handwriting font from lesson 20.1. And there's a box for an ad, which a tea farm pays for.

Asha opens the page on her phone. She starts to read the steps. Then the photo pops in, and the steps jump down. A moment later, the letters change shape, and everything moves up a little. Then the ad opens, and Add to cart drops off the bottom of her screen.

Here is her screen at four moments, as Chrome drew it:

Real frames of Asha's screen on Ravi's new mint tea page. 53 ms: no photo yet, steps in Arial. 724 ms: photo arrives, score 0.1829. 1329 ms: Caveat swaps in, score 0.0138. 2541 ms: the ad opens, score 0.0580.53 msAsha's screen at 53 ms: no photo yetno photo yetsteps in Arial724 msAsha's screen at 724 ms: photo arrivesphoto arrivesscore 0.18291329 msAsha's screen at 1329 ms: Caveat swaps inCaveat swaps inscore 0.01382541 msAsha's screen at 2541 ms: the ad opensthe ad opensscore 0.0580
Real frames from the course's recording in Chrome. Times count from the moment the page started loading. Each change pushed the page, and Chrome scored each push.

Ravi's page sends him its CLS after each visit. CLS, Cumulative Layout Shift, is Chrome's score for how much a page jumps. Lesson 30.1 showed how Chrome works it out. For Asha's visit, it was 0.2546. Over 0.25 is "poor". Ravi looks at the layout shifts behind it:

Asha's three jumpsPop out in the code editor (opens in a new tab)JavaScript
// Chrome's layout shifts on Asha's visit: [when, in ms; score; what moved].const shifts = [  [710.7, 0.18289, "#steps, #reviews, #add"],  [1323.7, 0.01378, "#reviews, #add, li, li, li"],  [1911.5, 0.05795, "#reviews, #add"],];for (const [time, score, moved] of shifts) console.log(`${time} ms: ${moved} moved. Score ${score}.`);console.log(`CLS: ${shifts.reduce((sum, [, score]) => sum + score, 0).toFixed(4)}`);
  • Line 1 is a comment. Times are in milliseconds (ms), from the moment the page started to load.
  • Lines 3 to 5 hold Chrome's three layout shifts. Each has its time, its score, and the elements Chrome listed as moved. Lesson 30.1 called that list the shift's sources.
  • Line 7 prints one line per shift. The first is 710.7 ms: #steps, #reviews, #add moved. Score 0.18289.
  • Line 8 adds up the scores. It prints CLS: 0.2546. The three came less than a second apart, so they fall in one session window: one burst of shifts.

Look at what Chrome listed: the steps, the reviews, Add to cart. None of them did anything. Each one was pushed. The thing that pushed isn't on the list. The Layout Instability spec says so: when a new element pushes content down, the sources "will report only the shifted elements, and not the inserted element."

So Ravi asks a fair question. "Chrome tells me what moved. What made it move?"

Real-life analogyA new book on a full shelf

Ravi's bookshelf is full. He pushes a new cookbook in at the left end, and every book to its right slides along. Ask the shelf which books moved, and it names every old book. It doesn't name the cookbook. The cookbook didn't move. It wasn't there before.

In real life: The books that slid along
In JavaScript: The sources Chrome lists: #steps, #reviews, #add
In real life: The new cookbook
In JavaScript: What made room: the photo, the font, the ad
In real life: Looking just left of the first book that moved
In JavaScript: Looking just above or beside the first element that moved
The main idea

A page jumps when something it shows takes new room after the first paint, the first time the browser draws the page. Chrome lists what moved. To find the cause, look for what made room.

Five common things make that room:

  • Images and videos without a size.
  • Ads, embeds and other iframes.
  • Content a script adds above what you're reading.
  • Web fonts that arrive late.
  • Animations of top, left, width or height.

web.dev names the first four as the most common causes of a poor CLS. The next five sections take one cause each. The course recorded every page in Chrome 157, on a screen the size of Asha's: 412 px wide and 823 px tall. Its server held some files back, the way a slow network would. The photo waited 700 ms, Caveat 1.3 seconds, and the ad's script 1.9 seconds.

Only Chromium browsers, like Chrome and Edge, write layout shifts. So CLS only comes from them:

Images and video without a size

Start with the biggest jump: the photo. Here is how Ravi's page shows it:

The photo, with no width or heightHTML
<style>#photo { display: block; width: 100%; height: auto; border-radius: 8px; }</style>
<img id="photo" src="mint-tea.jpg" alt="A glass of mint tea">
  • Line 1 is the photo's CSS. width: 100% makes it as wide as the page's column: 380 px on Asha's phone. height: auto means "work the height out from the photo's shape".
  • Line 2 is the tag. It has no width and no height.

The browser reads this tag long before the photo's file arrives. It knows the width. But it can't know the shape. A photo could be tall or wide. The file says its own size, in its first bytes. Until then, the browser makes the box 0 px tall.

Real-life analogyA parcel with no size on its label

A post office keeps parcels on a long shelf. When a label says how big a parcel is, the clerk clears that much space before it comes. When the label says nothing, the clerk leaves no space. Then the parcel arrives, and every parcel on the shelf gets pushed along.

In real life: The size on the label
In JavaScript: The width and height on the tag
In real life: Clearing shelf space before the parcel comes
In JavaScript: Keeping the photo's box before its file arrives
In real life: Pushing the other parcels along
In JavaScript: A layout shift when the file arrives

Here is what Chrome measured on Asha's phone:

The photo's box, before and after its filePop out in the code editor (opens in a new tab)JavaScript
// The photo's box on Asha's screen, in px: [width, height], from the recording.const beforeFile = [380, 0];const afterFile = [380, 253.4]; console.log(`Before the file arrived: ${beforeFile[1]} px tall.`);console.log(`After: ${afterFile[1]} px. Everything under it moved ${afterFile[1] - beforeFile[1]} px down.`);
  • Lines 2 and 3 hold the photo's box: its width and its height, before and after its file arrived.
  • Line 5 prints Before the file arrived: 0 px tall.
  • Line 6 prints After: 253.4 px. Everything under it moved 253.4 px down.

253.4 px is 380 px at the photo's shape, 1600 by 1067. The steps, the reviews and Add to cart all moved that far, at 710.7 ms. Together they covered most of the screen, so the score was big: 0.1829. That's more than two thirds of Asha's CLS, from one missing pair of attributes.

Lesson 18.3 showed the fix. MDN says: "Including height and width enables the aspect ratio of the image to be calculated by the browser prior to the image being loaded." An aspect ratio is a box's shape: its width divided by its height. The HTML standard says which tags get this. On img and video, the two attributes become an aspect ratio. CSS still decides the width, and the ratio gives the height.

A video starts in a default box

A video with no size isn't 0 px tall. The HTML standard gives it a default box, 300 px wide and 150 px tall, until it knows better. In Chromium, a video has no size of its own until its poster or its first bytes arrive. Ravi tried his brewing video both ways:

The brewing video, with and without its sizeHTML
<video id="brew" src="brew.mp4" muted playsinline></video>
<video id="brew" src="brew.mp4" width="640" height="360" muted playsinline></video>

Line 1 has no size. Line 2 has the video's own size, 640 by 360. Both pages make the video as wide as the column, like the photo. Here is what Chrome measured:

The video's box on each pagePop out in the code editor (opens in a new tab)JavaScript
// The video's box in px, [width, height], before and after the file's first bytes.const noSize = { before: [380, 150], after: [380, 213.75] };const withSize = { before: [380, 213.75], after: [380, 213.75] }; for (const [name, box] of Object.entries({ noSize, withSize }))  console.log(`${name}: the steps moved ${box.after[1] - box.before[1]} px`);
  • Lines 2 and 3 hold each page's box, before and after the file's first bytes.
  • Line 6 prints noSize: the steps moved 63.75 px and withSize: the steps moved 0 px.

Without a size, the box started 150 px tall: the default height. When the first bytes said 640 by 360, it grew to 213.75 px. The steps and Add to cart moved down 63.75 px, at 718.8 ms. The score was 0.0181. With the size, the box was 213.75 px tall from the start. Chrome wrote no layout shift at all.

A poster doesn't help on its own. Until the poster or the video's first bytes arrive, the box keeps the default size.

Why Ravi never saw the jump at his desk

Ravi works on a fast connection. On his own loads, the photo never jumped. The course loaded the same page with nothing held back. The photo was already 253.4 px tall when the browser finished reading the HTML, 18.4 ms in. That load's only layout shift came from the font.

Two rules explain it. The spec says nothing can shift in the first frame, because there's no earlier frame to compare with. And Chrome tries not to draw a frame that's missing an image. Chromium's notes for Chrome 118 say it picks an image's loading task before a drawing task, "to prevent layout shift of an intermediate frame that doesn't have the image."

Why it matters: a fast test can hide a missing size. Asha's slow phone can't. Give every image and video its width and height, even when your own tests look fine.

Try it with Ravi's real photo. The playground adds the photo's tag, then gives it its file a second later:

Playground: a photo with and without a size
What the playground does, shortenedJavaScript
const photo = document.createElement("img");if (withSize) Object.assign(photo, { width: 1600, height: 1067 });slot.append(photo); // the photo's box, before its file setTimeout(() => (photo.src = "mint-tea.jpg"), 1000); // the file "arrives" a second later
Ravi's photolive
Add to cart
before the fileno photo yet
after the filenot yet
layout shiftsnone
Try it yourself
Your browser

Pick a version, then press Load the photo. Its file arrives a second later.

This runs in your browser, with the Layout Instability API. The photo is the site's own file. The playground gives the photo its file a second after you press the button, the way a slow network would, so your click doesn't excuse the jump. Scores depend on the size of your window.

Ads, embeds and iframes

The third jump came from the ad. Ravi's page has an empty box for it, with the id ad. Nothing is in it, so it's 0 px tall. The ad network's script fills it when the script arrives. Here it is, shortened:

The ad network's script, shortenedJavaScript
// The ad server's script, shortened.const frame = document.createElement("iframe");frame.src = "http://ads.example/story/ad.html";frame.width = "300";frame.height = "250";document.querySelector("#ad").append(frame);
  • Line 2 makes an iframe: a box that shows a whole page from another address inside yours.
  • Line 3 points it at the ad's page, on the ad network's own site.
  • Lines 4 and 5 make it 300 px wide and 250 px tall.
  • Line 6 puts it in the empty box.

The script ran at 1911.5 ms. The reviews moved 266 px down: the ad's 250 px, plus a 16 px gap above it. Add to cart was pushed right off the bottom of the screen. The score was 0.0580.

Why do ads do this? web.dev says: "Ad networks and publishers often support dynamic ad sizes." So the page doesn't know which size will come. Embeds have the same problem. Videos, maps and social posts "often aren't aware of how large their contents are before they load." Lesson 19.2 kept a box for a video embed with aspect-ratio, and its shift went from 0.0677 to 0.

The iframe's own width and height can't save the slot. They arrive with the iframe, after the page has drawn the empty box. And the HTML standard doesn't turn an iframe's width and height into a shape. They only set its width and its height.

web.dev adds a warning: "Removing the space set aside for elements can cause just as much CLS as inserting content." A slot that closes up when no ad comes makes a jump too.

Real-life analogyA rented corner of the shop window

Ravi rents one corner of his shop window to the tea farm. He doesn't know what they'll put there until their van arrives. If they shuffle their display around inside the corner, that's their business. But people walking past see one window. They judge all of it.

In real life: The rented corner
In JavaScript: The ad's iframe, 300 × 250 px
In real life: The farm rearranging its corner
In JavaScript: A layout shift inside the ad's own page
In real life: People judging the whole window
In JavaScript: Chrome's own CLS, which counts the ad's jumps too
In real life: How big the corner is
In JavaScript: The share of the screen the ad covers

The jump nobody reported

The ad had a jump of its own. Its page has a picture and a line of text. The picture had no size either. When it arrived, at 2523.4 ms, the text moved 200 px down, inside the ad.

Ravi's script never saw it. An iframe holds a separate document: a whole page of its own. Chrome gives each document only its own layout shifts. The ad's page got the entry, with a score of 0.2110. It was worked out on the ad's own small screen, 300 by 250 px.

But Chrome counts it for itself. Chromium's layout_shift_tracker.cc scales a shift inside an iframe by the share of the screen the iframe covers. Chrome then adds that to its own CLS: the one in CrUX, Chrome's field data. web.dev agrees. CLS in iframes "is not measurable from Web APIs but is visible to the user," so CrUX includes it.

What the ad's jump addsPop out in the code editor (opens in a new tab)JavaScript
// The ad's own jump, inside its 300 × 250 px frame, on Asha's 412 × 823 px screen.const insideTheAd = 0.21099;const share = (300 * 250) / (412 * 823); console.log(`The ad covers ${share.toFixed(3)} of the screen.`);console.log(`Chrome adds ${(insideTheAd * share).toFixed(4)} to its own CLS.`);console.log(`Ravi's script: 0.2546. Chrome: ${(0.25462 + insideTheAd * share).toFixed(4)}.`);
  • Line 2 is the ad's own score.
  • Line 3 works out the ad's share of Asha's screen: its area, divided by the screen's area.
  • Line 5 prints The ad covers 0.221 of the screen.
  • Line 6 prints Chrome adds 0.0467 to its own CLS.
  • Line 7 prints Ravi's script: 0.2546. Chrome: 0.3013.

Chrome's own record of the load, its trace, holds the same number: a layout shift in the ad's frame, scaled to 0.0467.

Asha's screen at the end of the load, with the ad's 300 by 250 px box in the middle. Ravi's script: 3 shifts, CLS 0.2546. The ad's own page: 1 shift, 0.2110. The ad covers 0.221 of the screen. 0.2110 × 0.221 = 0.0467. Chrome's own CLS: 0.3013.Asha's screen with the ad open, and the reviews at the bottomthe ad: 300 × 250 pxRavi's script: 3 shifts, CLS 0.2546The ad's own page: 1 shift, 0.2110The ad covers 0.221 of the screen0.2110 × 0.221 = 0.0467Chrome's own CLS: 0.3013
The ad is a page of its own, so its jump goes to its own entries. Chrome's own count adds it, scaled down to the share of the screen the ad covers.

Why it matters: the ad's jumps count against Ravi's page in Chrome's data, and his own script can't see them. Choose ads and embeds that keep their own content still, and keep a box their size.

Try other ad sizes. The same jump costs more inside a bigger ad:

Playground: weigh an ad's own jump
What the playground works outJavaScript
// The same jump inside the ad, 0.21099, on Asha's 412 × 823 px screen.const share = (ad.width * ad.height) / (412 * 823);const added = 0.21099 * share; // what Chrome adds to its own CLSconst chrome = 0.25462 + added; // Ravi's script's CLS, plus the ad's part
Asha's screen300 × 250 px
share of the screen0.221
Chrome adds0.0467
Ravi's script0.2546
Chrome's own CLS0.3013
Try it yourself
Chrome adds 0.0467

A 300 × 250 px ad covers 0.221 of Asha's screen. The same jump inside it adds 0.0467, so Chrome's own CLS would be 0.3013.

It works out Chromium's rule: a shift inside an iframe is scaled by the share of the screen the iframe covers. The jump inside the ad stays the recorded 0.21099 for every size.

Content added above the fold

Newspapers are sold folded in half. The top half, "above the fold", is what you see first on the stand. On a web page, above the fold means what's on the screen before you scroll.

Lesson 30.1's banner was content a script added above the fold. It pushed most of the screen down. web.dev says content added near the top "usually causes greater layout shifts than content injected lower in the viewport." How much greater? Ravi tried the same notice in three places. Here is the script on one of the pages:

Adding a notice before the reviewsJavaScript
setTimeout(() => {  document.querySelector("#reviews").insertAdjacentHTML("beforebegin", '<p class="notice">Free delivery this week</p>');  performance.mark("notice");}, 600 - performance.now());
  • Line 1 sets a timer, and line 4 says when it fires: 600 ms after the page started.
  • Line 2 adds the notice, a yellow bar 112 px tall, just before the reviews.
  • Line 3 notes the moment, for the recording.

The other two pages add it in other places. One puts it before the tea, at the top. The other puts it before the footer, far below the screen. Here is each page after the notice came:

The same Free delivery notice, added 600 ms in, in three places on the same page. At the top: 4 elements moved, score 0.1182. In the middle: 3 elements moved, score 0.0497. Below the screen: nothing on screen moved, no entry.At the topThe page with the notice added at the top4 elements movedscore 0.1182In the middleThe page with the notice added in the middle3 elements movedscore 0.0497Below the screenThe page with the notice added below the screennothing on screen movedno entry
Real screenshots from the recording, after the notice arrived. The higher the notice goes, the more of the screen it pushes.
What Chrome wrote for each placePop out in the code editor (opens in a new tab)JavaScript
// The same 112 px notice, added in three places. Chrome's entries: [what moved, score].const top = [["#tea", "#more", "#reviews", "#add"], 0.1182];const middle = [["#more", "#reviews", "#add"], 0.0497];const below = [[], 0]; for (const [place, [moved, score]] of Object.entries({ top, middle, below }))  console.log(`${place}: ${moved.length} elements moved, score ${score}`);
  • Lines 2 to 4 hold what Chrome wrote for each page: what moved, and the score.
  • Line 7 prints top: 4 elements moved, score 0.1182 and middle: 3 elements moved, score 0.0497. Last comes below: 0 elements moved, score 0.

Everything moved 112 px, so the distance part of each score was the same. The difference was how much of the screen moved. At the top, everything under the header moved: a strip 775 px tall. In the middle, only the reviews, Add to cart and the teas under them moved. Below the screen, the footer moved, but nobody could see it. Chrome wrote no entry.

Real-life analogyJoining a queue at the front or the back

Ten people wait at the café counter. If someone pushes in at the front, all ten step back. If they join halfway down, five step back. If they join at the end, nobody moves at all.

In real life: Pushing in at the front
In JavaScript: A notice added at the top of the screen
In real life: Joining halfway down
In JavaScript: A notice added in the middle
In real life: Joining at the end
In JavaScript: A notice added below the screen
In real life: How many people step back
In JavaScript: How much of the screen moves: the impact fraction

Why it matters: if content has to arrive late, put it low on the page, or below the screen. Better still, keep its space from the start. Lesson 30.3 shows how. A click is different: lesson 30.1 showed that what a click adds in the next 500 ms doesn't count.

Web fonts that arrive late

The second jump came from Caveat. Here are the two lines of Ravi's CSS that matter:

Caveat, and the steps that use itCSS
@font-face { font-family: "Caveat"; src: url("caveat.woff2") format("woff2"); font-display: swap; }
#steps { margin: 12px 0 0; padding-left: 36px; font: 26px/1.3 "Caveat", Arial, sans-serif; }
  • Line 1 loads Caveat with font-display: swap. It means: show the steps in another font at once, and swap Caveat in when it arrives.
  • Line 2 puts the steps in Caveat, at 26 px. Until Caveat arrives, they use Arial.

The CSS Fonts spec gives swap "an extremely small block period" and "an infinite swap period". So the words appear in Arial straight away, and Caveat takes over whenever it comes. It came at 1323.7 ms.

Arial's letters are wider than Caveat's. In Arial, step 1 didn't fit on one line. In Caveat, it did. So the steps lost a line, and everything under them moved up 33.8 px. Chrome listed the reviews, Add to cart and three of the steps. The score was small, 0.0138, because the move was short. Lesson 20.3 met this same jump. There, the fallback was a stand-in actor of the wrong height.

Hiding the words doesn't stop the jump

What if the words stay hidden until Caveat arrives? That's font-display: block. The spec says the browser then draws the text "with an invisible fallback font face". That face has "the same metrics", the same sizes, as the fallback. So the hidden words take Arial's room. Ravi tried both, on a page with just the steps:

swap and block, side by sidePop out in the code editor (opens in a new tab)JavaScript
// The steps in Caveat, recorded with each font-display: [score, farthest move in px].const swap = [0.01378, 34.8];const block = [0.01339, 33.8]; console.log(`swap: score ${swap[0]}, farthest move ${swap[1]} px`);console.log(`block: score ${block[0]}, farthest move ${block[1]} px`);
  • Lines 2 and 3 hold each load's score, and how far its farthest element moved.
  • Line 5 prints swap: score 0.01378, farthest move 34.8 px.
  • Line 6 prints block: score 0.01339, farthest move 33.8 px.

Almost the same. Hiding the words didn't stop the jump. The boxes under them still moved 33.8 px.

The small difference is the words themselves. With swap, Chrome followed the text too, and one line of it moved 34.8 px. With block, the words were invisible. Chrome doesn't follow text it draws invisibly. Line 185 of layout_shift_tracker.cc skips it. So only the boxes counted.

Why it matters: a font swap is a layout shift like any other, and block doesn't avoid it. Lesson 20.3's fixes do. Give the fallback Caveat's sizes, or use font-display: optional, which never swaps in after the first paint.

Animating top, left, width and height

Some jumps don't come from loading at all. They come from the page's own animations. In lesson 30.1, a box slid 240 px with left, and Chrome wrote 24 entries, one per frame. The same slide with transform wrote none.

top, left, width and height are layout properties. They change where an element sits, or how much room it takes. Change one in every frame, and every frame can be a layout shift. web.dev: "Changing the top and left properties also cause layout shifts, even when the element being moved is on its own layer."

Ravi has an idea. What if the free delivery notice slid open, instead of appearing at once? Maybe a gentle slide doesn't count. He built a test page with two notices side by side. Each sits above the same 200 px box:

Two notices: one opens at once, one slidesCSS
.notice { height: 0; overflow: hidden; }.notice.is-open { height: 112px; }#notice-height { transition: height 300ms linear; }
  • Line 1 starts both notices closed: 0 px tall.
  • Line 2 opens a notice to 112 px when the page gives it the class is-open.
  • Line 3 makes the second notice slide open over 300 ms, instead of at once.
Two notices open on the same test page, pushing the same box 112 px. Opened at once: 1 entry, 0.0225 in all. Slid open, 300 ms: 17 entries, 0.0149 in all. Each thin bar is one layout-shift entry, as tall as its score; the wide bar on the right is all of them added up.Opened at once: 1 entry, 0.0225 in allSlid open, 300 ms: 17 entries, 0.0149 in all0 ms100 ms200 ms300 msin all
Drawn to scale, from the moment each notice started to open. Each thin bar is one entry, as tall as its score. The wide bar is all of them added up. Sliding open spread the jump over many frames. It didn't make it go away.

The first notice made one entry: 0.0225. The second made 17, one per frame. Each pushed the box about 6.2 px. Added up, they made 0.0149. All 17 came within one session window, so CLS counts them all.

So sliding open spread the jump over many frames. It came out smaller. In each frame, the box's old and new places overlapped, and an overlap counts once. But the jump didn't go away.

Real-life analogyDragging a table, or sliding its picture

Meera wants a table by the window. She could drag it slowly across the café. The people at the next table would still move their chairs, a little, every few seconds. Or she could slide a projected picture of a table across the wall. Nobody would move at all.

In real life: Dragging the table slowly
In JavaScript: Animating height or top
In real life: Chairs shuffled every few seconds
In JavaScript: A layout shift in every frame
In real life: Sliding a picture of the table across the wall
In JavaScript: Animating transform
In real life: Nobody moving a chair
In JavaScript: No layout shift at all

The same page also slid two toasts, small pop-up notes, 120 px down:

Two toasts: top and transformJavaScript
el("toast-top").animate([{ top: "448px" }, { top: "568px" }], { duration: 400, fill: "forwards" });
el("toast-transform").animate([{ transform: "translateY(0)" }, { transform: "translateY(120px)" }], { duration: 400, fill: "forwards" });
  • Line 1 slides one toast 120 px over 400 ms by changing top.
  • Line 2 slides the other the same way with transform.

Last, a badge grew 150 px wide next to a price. Here is everything Chrome wrote:

What Chrome wrote for each movePop out in the code editor (opens in a new tab)JavaScript
// Chrome's entries for each move on the test page: [how many, their scores added up].const moves = {  "opened at once": [1, 0.0225],  "slid open with height": [17, 0.0149],  "slid with top": [24, 0.0100],  "slid with transform": [0, 0],  "grew with width": [18, 0.0028],};for (const [move, [entries, sum]] of Object.entries(moves))  console.log(`${move}: ${entries} ${entries === 1 ? "entry" : "entries"}, ${sum.toFixed(4)} in all`);
  • Lines 3 to 7 hold each move: how many entries, and their scores added up.
  • Lines 9 and 10 print one line per move, from opened at once: 1 entry, 0.0225 in all to grew with width: 18 entries, 0.0028 in all.

The toast that slid with top wrote 24 entries, one per frame, 5 px each. The transform toast wrote none. The spec checks each element's place twice: as drawn, and as if it had no transform. A move only counts if both changed. Chromium does this on lines 266 to 270 of layout_shift_tracker.cc.

And width pushed the price sideways, 8.3 px a frame. width moves what sits beside an element. height moves what sits below it.

Animations that start with a click

What if a click starts the animation? Lesson 30.1 showed that CLS skips shifts less than 500 ms after a click. Ravi's Show reviews button opens the reviews with a height transition of 900 ms. The course clicked it with the mouse.

Chrome wrote 43 entries, one per frame. The first came 8.5 ms after the click, and the last 890.9 ms after it. The 19 inside the first 500 ms had the flag hadRecentInput set, which marks a shift right after input. CLS skipped them. The other 24 counted. The page's CLS was 0.0097, all from the end of one animation.

web.dev warns about transitions "which take longer than the 500 millisecond grace period". Why it matters: if a click opens something, finish moving it within 500 ms, or move it with transform. Lesson 30.3 shows how.

Try all three in your own browser. Each move starts on your click, like Ravi's reviews:

Playground: three ways to move a box
The playground, shortenedJavaScript
button.onclick = () => {  box.animate(frames[how], { duration: 1200 }); // 120 px down and back, with top, height or transform};new PerformanceObserver((list) => {  for (const shift of list.getEntries()) count(shift.hadRecentInput ? "skipped" : "counted", shift.value);}).observe({ type: "layout-shift" });
The boxlive
Added to cart
entries0
skipped, in the first 500 ms0
counted0
Try it yourself
Your browser

Press a button. The box moves 120 px down and back up, over 1.2 seconds. Then compare the three.

This runs in your browser, with the Layout Instability API. Each move starts on your click, so the frames in the first 500 ms are skipped. Scores depend on the size of your window.

Which cause made this jump?

Here are Ravi's four jumps again, each traced to its cause. Read each row across: the jump, what Chrome listed, what made room, and the score.

Ravi's jumps, traced to their causes
The jumpWhat Chrome listed as movedWhat made roomScore
The photo, at 710.7 ms#steps, #reviews and #add, all 253.4 px down.The photo had no width or height. Its file gave the box its height.0.1829.
The font, at 1323.7 ms#reviews, #add and three steps, 33.8 px up.Caveat swapped in. Its letters are narrower, so step 1 lost a line.0.0138.
The ad, at 1911.5 ms#reviews, 266 px down, and #add, off the screen.The ad script put a 300 × 250 px iframe in the empty slot.0.0580.
Inside the ad, at 2523.4 msThe ad's text, 200 px down, inside the ad.The ad's own picture had no size either.0.2110 in the ad. Chrome adds 0.0467.

Now try some new ones. Sort each change by its cause:

Which cause made this jump?
  • A product photo styled width: 100%, with no width or height, arrives late
  • A video with no size gets its first bytes
  • A map from another site loads into an empty box
  • The ad network sends an ad taller than the slot
  • A video player's script puts its iframe in an empty div
  • A cookie notice appears above the header two seconds in
  • Reviews from fetch() fill an empty section above Add to cart
  • A heading's handwriting font arrives, and its lines get shorter
  • Text hidden by font-display: block appears in its real font
  • An accordion opens by animating its height over 400 ms
  • A toast slides in by animating top
Try it yourself
0 of 11 correct

Sort each change by what made room.

Choose a category for every card. You can change an answer at any time; Reset clears them all.

Common mix-ups

  • "The element in the sources caused the shift." No. The sources are what moved. The photo, the ad and the notice were never listed. They made the room.
  • "width: 100% in CSS is enough for an image." No. It gives the width, not the shape. Without width and height, the box is 0 px tall until the file arrives.
  • "A missing size only matters on slow phones." No. It matters whenever the file comes after the first paint. A fast test only hides it.
  • "width and height on an iframe keep its shape, like on an image." No. The HTML standard turns them into a shape only for images, videos, canvases and image buttons.
  • "If an ad jumps inside its own box, the page is fine." No. Chrome's own CLS adds it, scaled by the ad's share of the screen. Ravi's 0.2546 became 0.3013.
  • "font-display: block avoids the font's jump." No. The hidden words take the fallback's room. Block scored 0.0134, against 0.0138 with swap.
  • "A slow, smooth animation doesn't count." No. Every frame that moves something 3 px or more is a layout shift. Sliding open made 17 of them.
  • "Anything a click starts is excused." No. Only the first 500 ms. 24 frames of Ravi's 900 ms transition counted.

Practice exercises

Answer first, then use the hints.

Exercise 1 · Warm-upThe wrong size

Ravi copied an old tag with width="400" and height="300". The photo is really 1600 by 1067. What does the last line print?

Starter codePop out in the code editor (opens in a new tab)JavaScript
// Ravi's tag says width="400" height="300". The photo file is 1600 × 1067 px.
const shown = 380; // px wide on Asha's screen
const before = shown * (300 / 400);
const after = shown * (1067 / 1600);

console.log(`Before the file: ${before} px tall.`);
console.log(`After: ${after.toFixed(1)} px tall.`);
console.log(`The text under it moves up ${(before - after).toFixed(1)} px.`);

Answer, then press Check. Spacing and letter case don’t matter.

    Exercise 2 · Warm-upA smaller ad

    Say the same jump, 0.21099, happened inside an ad 320 px wide and 50 px tall. What does the second line print?

    Starter codePop out in the code editor (opens in a new tab)JavaScript
    // The ad's own jump, inside its 320 × 50 px frame, on Asha's 412 × 823 px screen.
    const insideTheAd = 0.21099;
    const share = (320 * 50) / (412 * 823);
    
    console.log(`The ad covers ${share.toFixed(3)} of the screen.`);
    console.log(`Chrome adds ${(insideTheAd * share).toFixed(4)} to its own CLS.`);
    console.log(`Ravi's script: 0.2546. Chrome: ${(0.25462 + insideTheAd * share).toFixed(4)}.`);

    Answer, then press Check. Spacing and letter case don’t matter.

      Exercise 3 · PracticeA tall ad

      In the weigh-an-ad playground, pick the ad 300 px wide and 600 px tall. How much does Chrome add, to four decimal places?

      Answer, then press Check. Spacing and letter case don’t matter.

        Exercise 4 · PracticeWhich box will jump?

        Each file here arrives late, after the page first painted. Which line's box changes size when its file arrives?

        Starter codePop out in the code editor (opens in a new tab)JavaScript
        <img src="logo.png" width="120" height="40" alt="Leaf and Kettle">
        <video src="brew.mp4" muted playsinline></video>
        <iframe src="map.html" width="380" height="240" title="Map to the shop"></iframe>
        <p>Open every day, 8 to 6.</p>

        Answer, then press Check. Spacing and letter case don’t matter.

          Exercise 5 · ChallengeThe shape in DevTools

          Open the course's copy of the sized video page in Chrome. Select the video in DevTools' Elements panel. What does the aspect-ratio line in its Attributes Style say?

          Answer, then press Check. Spacing and letter case don’t matter.

            Exercise 6 · ChallengeWhat the tracker never watches

            In Chromium's layout_shift_tracker.cc, the function NeedsToTrack decides what Chrome watches. Besides invisible text, one kind of element is never watched at all. Which kind?

            Answer, then press Check. Spacing and letter case don’t matter.

              Check your understanding

              For each question, ask which cause it's about, and what made room.

              The what causes layout shifts quiz · 8 questionsScore: first tries count
              1. Question 1 of 8What does the second line of the ad example print?

                Read the code, then predictPop out in the code editor (opens in a new tab)JavaScript
                // The ad's own jump, inside its 300 × 250 px frame, on Asha's 412 × 823 px screen.
                const insideTheAd = 0.21099;
                const share = (300 * 250) / (412 * 823);
                
                console.log(`The ad covers ${share.toFixed(3)} of the screen.`);
                console.log(`Chrome adds ${(insideTheAd * share).toFixed(4)} to its own CLS.`);
                console.log(`Ravi's script: 0.2546. Chrome: ${(0.25462 + insideTheAd * share).toFixed(4)}.`);

                Choose an answer to see the explanation.

              2. Question 2 of 8What does the first line of the video example print?

                Read the code, then predictPop out in the code editor (opens in a new tab)JavaScript
                // The video's box in px, [width, height], before and after the file's first bytes.
                const noSize = { before: [380, 150], after: [380, 213.75] };
                const withSize = { before: [380, 213.75], after: [380, 213.75] };
                
                for (const [name, box] of Object.entries({ noSize, withSize }))
                  console.log(`${name}: the steps moved ${box.after[1] - box.before[1]} px`);

                Choose an answer to see the explanation.

              3. Question 3 of 8On the fast load of Ravi's page, why did the photo make no layout shift?

                Choose an answer to see the explanation.

              4. Question 4 of 8On which element do width and height not give the browser a shape before the content arrives?

                Choose an answer to see the explanation.

              5. Question 5 of 8The ad's own picture pushed the ad's text down, inside its iframe. What did Ravi's own layout-shift observer see?

                Choose an answer to see the explanation.

              6. Question 6 of 8A script must add a notice while the visitor reads. Where does it move the least?

                Choose an answer to see the explanation.

              7. Question 7 of 8Does font-display: block stop the jump when the web font arrives?

                Choose an answer to see the explanation.

              8. Question 8 of 8A menu slides open with a height transition that starts on a tap and runs for 900 ms. Which of its frames count toward CLS?

                Choose an answer to see the explanation.

              Key takeaways

              • Chrome lists what moved, not what made it move. Look just above or beside the first element that moved.
              • An image or video without width and height has no shape until its file arrives: 0 px tall for an image, 300 by 150 for a video.
              • An ad or embed in an empty slot pushes the page when it arrives. Its own jumps count in Chrome's CLS too, scaled by its share of the screen.
              • Content added near the top moves more of the screen than content added lower down. Below the screen, it moves nothing anyone sees.
              • A web font that arrives late changes how much room the words take. Hiding them with block doesn't help.
              • Animating top, left, width or height makes a shift in every frame. transform makes none. A click excuses only the first 500 ms.

              Remember the one-liner.
              A page jumps when something takes new room after the first paint: Chrome tells you what moved, and you look for what made room.

              Sources

              The facts on this page come from these specs, docs and source files:

              Coming next: Fixing layout shifts. Keeping space for images, ads and late content, and moving things with transform, so none of these jumps happen.

              CompleteFrontend Clear concepts. Working examples.