CLS Debugger Fixes: Track Down What Moves and Stop It

How a layout shift is counted

The browser reports a layout shift whenever an element that was already visible changes its start position between two frames. New content appearing is not a shift in itself; the shift is the existing content being pushed out of the way.

Each shift gets a score made of two parts multiplied together:

• Impact fraction. How much of the viewport was affected, counting the area the moving elements covered before and after the move.
• Distance fraction. How far the elements moved, as a proportion of the viewport's larger dimension.

So a small badge moving a long way and a large block of text moving a little can score about the same. A full-width banner that pushes the whole article down by a quarter of the screen scores highly on both.

Session windows

Shifts are grouped into bursts called session windows. A window keeps growing while shifts happen less than a second apart, up to a maximum of five seconds. The page's CLS is the total of the worst single window, not the sum of everything that happened during the visit. That is why a long page with occasional small shifts can still pass, while one bad burst during load can fail it on its own.

What does not count

Shifts within 500 milliseconds of a click, tap or key press are excluded, because the visitor expects the page to change when they act. Moving things with CSS transform animations does not count either, since transforms do not change layout. Scrolling does not exclude shifts, however: content that jumps as it lazy-loads during scrolling still counts.

Tracing a shift back to its cause

The debugger gives you the element that moved. That is often not the element that caused the move. If a banner appears at the top of the page and pushes the article down, the report shows the article's paragraphs shifting; the banner is the culprit. Always ask "what appeared or changed size just above this?"

Reproducing it yourself

1. Open the page in Chrome with DevTools, go to the Performance panel and record a page reload. Layout shifts appear as their own track; select one to see the nodes that moved and their old and new positions.
2. Switch on network and CPU throttling. Many shifts only happen when an image, font or script arrives late, and on a fast connection everything lands before the first paint.
3. Repeat with the cache disabled and in a private window, so you see the cookie banner and first-visit behaviour real newcomers get.
4. Scroll slowly down the page while recording, because lazy-loaded content and sticky elements often shift further down.

Logging shifts in the console

The Layout Instability API lets you list each shift and its source nodes directly. Paste this into the console before reloading, or add it temporarily to the page:

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.hadRecentInput) continue;
    console.log(entry.value.toFixed(4),
      entry.sources.map((s) => s.node));
  }
}).observe({ type: 'layout-shift', buffered: true });

For real visitors, the attribution build of Google's web-vitals library reports the element responsible for the largest shift, which you can send to your analytics to find shifts that only happen on certain devices or journeys.

Matching what you see to the likely cause

Once you know which element moved and roughly when, the cause is usually one of a small set of patterns. Use this table to go from the symptom to the right guide.

The fix guides

Each guide covers one source of shifting: how to confirm it is the cause and how to reserve space or change the loading pattern so nothing moves.

Media and embeds

Fixing CLS from images without dimensions shows how width and height attributes, or the CSS aspect-ratio property, let the browser reserve the right box before the file arrives. Fixing CLS from responsive image swap covers srcset and art-directed sources whose proportions differ, and how to lock the box whatever file is chosen. Fixing CLS from video and iframe embeds covers YouTube, Vimeo, maps and social posts, using a fixed-ratio wrapper.

Text and fonts

Fixing CLS from web font swap covers font-display choices, preloading key fonts, and adjusting the fallback font with size-adjust and related descriptors so the swap barely moves anything.

Content added after load

Fixing CLS from ad slots covers reserving a fixed size per slot and handling slots that sometimes stay empty. Fixing CLS from late-loaded components covers skeleton placeholders and minimum heights for widgets rendered by JavaScript. Fixing CLS from dynamic content insertion covers newsletter prompts, cookie notices and age gates, and when to overlay rather than insert. Fixing CLS from cart and notification banners covers "added to basket" bars and alerts that should sit on top of the page, not inside it.

By platform

WordPress covers page builders that output images without dimensions, lazy-loaded blocks and ad plugins. Shopify covers app-injected blocks, announcement bars, theme fonts and product image variants. React and Next.js covers hydration differences, lazy components with placeholders, and the built-in image and font components.

Which shifts to fix first

Because CLS is the score of the worst burst, not the total, you get the biggest improvement by fixing the largest shifts in that burst. The debugger ranks shifts by their contribution, so start at the top of its list.

1. Shifts that affect every page. A header, cookie notice, announcement bar or web font is shared across the site, so one fix improves every template at once.
2. Shifts above the fold during load. These are what every visitor sees, and they tend to be large because they push the whole page down.
3. Shifts near buttons and links. Anything that can make someone tap the wrong thing, such as a "Buy" button moving just as a promo bar appears, costs you sales and trust even if the score is small.
4. Shifts further down the page. Lazy-loaded images and ads in long articles matter too, but they usually score lower and affect fewer visitors.

Small shifts under 0.01 each are rarely worth chasing individually unless several of them land in the same session window and add up.

Order of work

1. Record the shifts. Run the CLS Debugger on each main template and note the top shifts, the elements named and roughly when they happen.
2. Identify the cause, not just the mover. For each big shift, find the element above it that appeared or changed size.
3. Reproduce it locally. Use throttling and a fresh private window so you can see the shift happen and confirm your fix removes it.
4. Reserve space or overlay. Give media fixed proportions, give ad slots and widgets a minimum height, and move notices into fixed or sticky positions that sit over the content.
5. Fix the fonts. Match the fallback font's size to the web font, or use a font-display value that avoids a late swap.
6. Re-run the debugger. Confirm the shift has gone and that no new one has appeared lower down.
7. Watch real-user data. Field CLS improves over the following weeks as older visits age out of the reporting window.

For more background, see the CLS Guide. If layout shift is one of several speed problems, the page speed fixes cover server response and page weight, and the image optimisation fixes cover image sizing in detail.