CLS Layout Shift Debugger Guide: Find and Fix Jumpy Pages

You have tapped a button just as the page moved, and hit something else instead. That jump is layout shift, and Cumulative Layout Shift, or CLS, is the metric that measures it. The CLS Layout Shift Debugger finds which elements shift, when they shift, and how much each shift contributes, so you can fix the jump rather than guessing at it.

CLS is one of Google's Core Web Vitals, the user-centred metrics used to assess page experience. It accumulates the scores of unexpected layout shifts during the life of a page, excluding shifts that happen within 500 milliseconds of a user interaction, such as a tap that intentionally expands a menu. Each shift score is the product of two fractions: the impact fraction, the share of the viewport affected by the moving elements, and the distance fraction, the distance the largest moving element travels relative to the viewport's larger dimension. A shift that moves a large area a long way scores high; a shift that moves a small element slightly scores low. The total CLS is the sum of shift scores within session windows, which group shifts that occur close together in time.

The thresholds are simple to remember. A CLS below 0.1 is considered good, between 0.1 and 0.25 needs improvement, and above 0.25 is poor. These are field thresholds based on real user visits, while lab tools report a simulated value for a single load. A page can pass in the lab and fail in the field if real users have slower connections, different screen sizes or interactions the lab did not simulate, so treat lab scores as a debugging aid and field data as the verdict where available.

The usual culprits are few. Images and videos without width and height attributes cause shifts when the browser first reserves no space and then expands the element once the media loads. Web fonts cause shifts when fallback text is replaced by the loaded font at a different size. Ads and embeds cause shifts when a container with no reserved height suddenly fills. Late-injected content, such as a banner or a related-posts block inserted above existing content, pushes everything below it down. Animations that change layout properties, rather than transform properties, also shift the page, while transform-based animations move elements visually without changing layout and do not count as shifts.

A worked example you can follow

Suppose a debugger reports two shifts in one session window. The first shift affects 40 percent of the viewport, an impact fraction of 0.40, and the largest element moves 30 percent of the viewport height, a distance fraction of 0.30. Multiply: 0.40 times 0.30 equals 0.12. The second shift affects 20 percent of the viewport, 0.20, and moves 40 percent, 0.40, giving 0.20 times 0.40, which equals 0.08. Add the two scores: 0.12 plus 0.08 equals 0.20. A total CLS of 0.20 falls in the needs-improvement band, above the 0.10 good threshold and below the 0.25 poor threshold. The arithmetic also shows where to focus: the first shift contributes more, 0.12 against 0.08, so fixing the element behind the first shift moves the total further than fixing the second.

Fix the first shift by reserving space. If it is an image, add width and height attributes or an aspect-ratio style, so the browser reserves the correct box before the image arrives. The Aspect Ratio Calculator helps you compute that box. If it is an ad, give the slot a fixed minimum height matching the most common creative size. If it is a font swap, use a fallback font with similar metrics and a font-display strategy that limits the swap window. Re-run the debugger after each fix: CLS should fall as the reserved space takes effect, and the remaining shifts will point to the next culprit.

Common mistakes to avoid

The most common mistake is fixing only the largest single shift and ignoring the accumulation: many small shifts can sum to a poor total. A second mistake is testing only on a fast connection and a large screen, where shifts are smaller and later content arrives sooner. A third mistake is reserving space with a fixed height that breaks on narrow screens, trading a shift for an overflow. A fourth mistake is inserting content above existing content after load, such as a consent banner that pushes the article down; reserve its space in advance or overlay it instead. A fifth mistake is chasing a perfect zero: some shifts come from user actions or unavoidable late content, and a stable score below 0.1 is the practical goal.

Debug in layers. First, run the tool on a cold load and list every shifting element. Second, fix reserved space for media and embeds. Third, address font behaviour. Fourth, check interactions: expanding accordions and infinite scroll should not shift unrelated content unexpectedly. Fifth, re-test on a slow connection and a small viewport, where shifts are worst. Pair CLS work with the Browser Cache Policy Builder for repeat-visit speed, since cached assets shift less on return visits.

Frequently asked questions

Does CLS include shifts after I interact with the page? Shifts within 500 milliseconds of an interaction are excluded, because they are usually expected consequences of the interaction. Shifts later than that, or unrelated to the interaction, still count.

Why does my page shift only sometimes? Because shifts depend on load timing: slow images, slow fonts and late third-party content shift more on slow connections, and different screen sizes change impact fractions. Test across conditions, not just your own fast setup.

Can animations cause CLS? Layout animations, which change width, height or position in layout, can. Transform and opacity animations do not change layout and do not contribute to CLS, which is why they are preferred for movement effects.

For performance background, see How to Perform a Website SEO Audit Step by Step. Layout stability is a courtesy to readers: reserve the space, load in place, and let people tap what they meant to tap.