What the CLS Layout Shift Debugger does
This debugger takes the layout-shift entries recorded on your own page, groups them into the session windows that Cumulative Layout Shift is built from, names the elements that moved and by how much, and suggests the likely cause of each shift - unsized images, injected ads and banners, or text that changed size when a web font arrived.
You record the entries with a short console snippet (or a saved DevTools trace), paste them here and everything is analysed in your browser tab. The CLS it shows is for that one load: a lab figure, not the field 75th percentile that Google assesses.
How to use it
- Open the page in Chrome or Edge with a phone-sized viewport (DevTools device mode) and, ideally, network throttling - late content is what causes most shifts.
- Paste the snippet into the DevTools Console and press Enter. Shifts since the page loaded are buffered, so you do not need to reload.
- Scroll through the page and wait a few seconds for ads, consent banners and embeds to arrive, then run
a2zDump()to copy the JSON. - Paste it here (or drop a saved Performance trace) and press Analyse.
- Start with the worst session window and the largest shift inside it; the Elements and Movement columns tell you what moved and how far.
Reading the results
A session window is a burst of shifts less than one second apart, lasting at most five seconds. CLS is the score of the largest window, not the sum of every shift on the page - so fixing a small shift in the worst window can matter more than a large one elsewhere.
Shifts within 500 ms of a tap, click or key press carry hadRecentInput and are excluded: expanding an accordion is expected movement. They are listed but never counted.
Movement shows each source element's position and height before and after the shift, in CSS pixels. An element whose height grew from 0 is usually the cause; elements whose y position increased are usually the victims being pushed down.
The causes are A2Z heuristics based on element names and geometry. They point you at the right element; confirm the cause in the page itself.
Worked example: a news article with a CLS of 0.102
The sample load has five shifts. At 380 ms the headline grows from 76 to 114 px tall in place as the web font swaps in (0.012). At 820 ms the hero image, which had no height, becomes 211 px tall and pushes the article body down (0.09). These are 440 ms apart, so they form window 1: 0.012 + 0.09 = 0.102.
At 2,600 ms an ad slot opens to 250 px (0.06) and at 3,100 ms a cookie banner pushes the header down (0.04). The gap from 820 ms is 1,780 ms, so they start window 2, scoring 0.10. A 0.21 shift at 9,400 ms came straight after the reader opened an FAQ answer and is excluded.
CLS is the larger window: 0.102, just over the 0.1 good threshold. Adding width and height to the hero image removes 0.09 and drops CLS to 0.10 (window 2) - so the ad slot and the banner need reserved space too before the page is comfortably good.
Formulas and scoring rules
- Session window
a shift joins the current window if (start - previous shift start) < 1000 ms and (start - window start) < 5000 msOtherwise it starts a new window. Shifts with hadRecentInput are skipped.- Window score
window = sum of the layout-shift values in it- CLS
CLS = max(window scores)Shown to three decimals; 0 when there are no counted shifts.- Layout-shift value (browser)
value = impact fraction x distance fractionComputed by the browser; the tool reads it, it does not recompute it.
The usual causes, and the fix for each
Images, videos and iframes without dimensions. Give them width and height attributes (or CSS aspect-ratio) so the browser reserves the box before the file arrives. This is the most common and the easiest fix.
Ads, embeds, consent banners and promos inserted above content. Reserve the slot's height with min-height, or overlay banners with fixed positioning instead of pushing the page down.
Web fonts. When the fallback font and the web font have different metrics, text reflows as the font swaps. size-adjust, ascent-override and descent-override on the fallback @font-face can make them match; the Web Font Loading Optimizer generates them.
Limitations: what the result does not prove
- One load in one browser is lab data. Field CLS is the 75th percentile across real visits and includes shifts during long sessions, such as infinite scroll.
- Element descriptions are tag, id and the first classes, taken when the shift happened. Elements removed afterwards, or trace node ids, may not identify the element on their own.
- Likely causes are heuristics from names and geometry; a shift can have a cause the heuristics do not recognise.
- The browser only reports shifts of elements visible in the viewport, so a shift below the fold during load will not appear until the visitor scrolls there.
Privacy: where your data goes
Everything you paste, type or drop is processed in this browser tab. It is not uploaded, logged, stored or sent to analytics. Session recording and tag-manager scripts are switched off on this page.
Standards and sources
- web.dev - Cumulative Layout Shift - checked 19 Sep 2026
- web.dev - Web Vitals and thresholds - checked 19 Sep 2026
- web.dev - Optimize Cumulative Layout Shift
- W3C Layout Instability API
Frequently asked questions
What counts as a single layout shift session window?
Shifts that follow each other with less than one second between them belong to the same window, up to a total length of five seconds. A pause of a second or more, or reaching five seconds, starts a new window. CLS reports only the highest-scoring window.
Why was a large shift ignored?
It happened within 500 ms of a click, tap or key press, so the browser marked it with hadRecentInput. Movement that directly follows what the visitor did, such as opening a menu, is expected and is excluded from CLS by design.
Which element should I fix: the one that grew or the ones that moved?
Usually the one that grew or appeared - an image whose height went from 0, an ad slot, a banner. The elements that moved down are victims. Reserving space for the element that appeared stops all of them moving.
Can a web font cause layout shift?
Yes. When a fallback font is replaced by a web font with different widths or line heights, text blocks change size and push content around. Matching the fallback's metrics with size-adjust and the override descriptors, or using font-display: optional, avoids it.
My lab CLS is 0 but Search Console reports a problem. Why?
Field CLS covers the whole visit on real devices, including shifts after scrolling, late ads that do not load in your test, slow connections and personalised content. Record on a throttled phone-sized viewport and scroll the full page to reproduce it.
Does CSS transform animation cause layout shift?
No. Animating transform or opacity does not move elements in the layout, so it never produces layout-shift entries. Animating top, left, height or margin does, which is why transforms are the recommended way to animate.
Last reviewed by the A2Z.Tools team against the sources listed above.
