CLS Debugger

About the Cumulative Layout Shift Debugger

The purpose of the Cumulative Layout Shift Debugger is to visualize the cumulative layout shifts of any webpage so it becomes easier to identify what needs improving on mobile and/or desktop in the initial load of a website.

The Cumulative Layout Shift Debugger uses the Layout Instability API in Chromium to detect and measure the layout shifts in the viewport between when a webpage starts loading and when it finishes loading and calculates its cumulative layout shift score. The squares in the image are where shifts are happening and the list of html elements help identify the culprits in the code base, and depending on the scores these may require fixing.

During the tests the CPU and network are throttled. Currently only Moto G4 for mobile and a standard desktop (1920x1080) are supported. Report links are accessible, shareable and available for 31 days after generation.

The Chrome User Experience Report data is pulled from the Google Chrome UX Report API for the webpage and relevant origin in question to provide extra context.

How to fix the Cumulative Layout Shift score?

Cumulative Layout Shift is a Core Web Vital metrics which measures the instability of content by summing shift scores across layout shifts that don't occur within 500ms of user input. It looks at how much visible content shifted in the viewport as well as the distance the elements impacted were shifted. The most common causes for CLS and its potential solutions are:

• Images without predefined dimensions, which can be addressed by utilizing responsive images (e.g. srcset) and always adding width and height dimensions to all images loaded.
• Ads, embeds, and iframes without dimensions, which can be addressed by reserving the space for the object using CSS. For example, even when the object may not have been loaded yet, the space is already reserved as a empty space or with a placeholder in which the object can be loaded. Make sure to reserve the space with the proper dimensions, this especially applies also to iframes and embeds. In addition, avoid placing non-sticky ads near the top of the viewport and avoid collapsing the reserved space when no object is loaded. General best practice: load the object below the fold when ever possible.
• Dynamically injected content, which in general is best avoided unless in response to a user interaction. This especially applies to anything above fold and/or inserting new content above existing content.
• Web fonts causing a Flash of Invisible Text (FOIT) or Flash of Unstyled Text (FOUT), which can be addressed by utilizing font-display and rel=preload.
• Actions waiting for a network response before updating the DOM, which can be addressed by making sure the response to any user action is less than 500ms and utilizing CSS transform animations instead of animations of properties that trigger layout changes like re-layout, paint and composite. For example, if a user clicks a "load more" button be sure to load, reserve the space ASAP for the additional content within the 500ms of the click and utilize rel=prefetch to cache the results so they can be loaded within the 500ms. In addition, be sure to remove or move out of viewport any footer or elements which may be pushed down by the action of injecting more content when a "load more" button is clicked.
• Grid layout containers initially visible upon loading but hidden straight after (e.g. print related layout or cookie interstitials) or containers without dimensions reserved in critical CSS, which can be addressed by updating the critical CSS in the initial HTML load and re-evalutating what to load when.

Known Issues

• The CLS Debugger will try several times to render the webpage. If a webpage takes more than 30 seconds to respond and render, the test may end up failing.
• The CLS Debugger may be blocked by the server or the CDN due to agressive bot blocking rules. Unfortunately, we have no control over this. However if this is a website you own, you can try to whitelist the CLS Debugger in the server or CDN settings. Each HTTP request from the CLS Debugger is made with a unique X-Request-Id (starting with webvitals.cls.) and Referer (starting with https://webvitals.dev/) HTTP header to avoid being blocked.
• Sometimes a live test may go wrong and may not report the actual Cumulative Layout Shift score and defaults to zero. The best solution for now is to try later again.
• If a webpage is restored from the back/forward cache, its Cumulative Layout Shift score is likely reset to zero since users experience this as a distinct webpage visit.
• Unfortunately the Chromium Layout Instability does not report layout-shift entries for shifts that occur within iframes, so this tool may not capture these either. Try to test the iframes seperately from the primary webpage.
• When a lot of movement is happening on a webpage, especially vertical movement, this can make it difficult to determine which elements have shifted. Try to fix some of the larger shifts before narrowing down the smaller shifts.
• The output of this tool may be significantly impacted if a webpage is in any way blocked from rendering in full in Chromium, e.g. full webpage cookie popup, language/geo IP redirects or self signed SSL certificates, etc.
• Single Page Applications, due to the nature of navigating between pages on the "same page", can be misinterpreted by the browser APIs and record misleading metrics for measuring web vitals. Be sure to first reload the page before measurement.
• If a webpage is in the background state for its entire lifetime, it will likely not report any Cumulative Layout Shift score.
• Users with a slower internet connection or computer will most likely experience higher Cumulative Layout Shift scores because there are more layout changes necessary to accommodate the asynchronous resources. In situations when a large number asynchronous resources are loaded and rendered, the Cumulative Layout Shift scores will change based on the arrival and execution time of those resources. Try to optimize the viewport for slower connections and lower CPU requirements, in general this means load less resources like Javascript and avoid (expensive) CSS effects. Be aware that if the website's real users meet this criteria, the Cumulative Layout Shift scores from the Chrome User Experience Report are also impacted. Know what the website's real users are using and optimize the website for these resources.
• The Cumulative Layout Shift score is calculated based on viewport size, so likely the Cumulative Layout Shift scores will be higher for mobile users because the viewports are smaller and the impact of each shift as a percentage is therefore larger in the calculation of the Cumulative Layout Shift score.
• Large interstitials (e.g. for cookie acknowledgements) can prevent the Cumulative Layout Shifts to be recorded as displaying the interstitials prevents the content in the viewport from visibly loading and/or changing.
• Keep in mind that the Cumulative Layout Shift Debugger can only identify layout shifts that occurred during the initial page load.
• Occasionally, bugs are discovered in the APIs used by the Cumulative Layout Shift Debugger to measure metrics, and sometimes in the definitions of the metrics themselves, and sometimes in the code base of the Cumulative Layout Shift Debugger itself. As a result, changes are made when needed, and these changes can show up as improvements or regressions in the reports. Run the report frequently to get the latest metrics.