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.
• 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.

Frequently Asked Questions

How to use the experimental cookie interstitial feature?

First of all, keep in mind that using this feature may impact (either positively or negatively) the Cumulative Layout Shift scores. Therefore it is highly recommended to perform tests for both scenarios.

To utilize the experimental feature, fill in the URL.

Next, add the text of the HTML element to click, often this is "Accept", "Accept all", "Verstanden" (German) or "OK", etc.

Optionally but highly recommended
Next, check what type of HTML element this text is located in. Currently only 'button', 'div', 'span' and 'a' are supported. If one is missing, contact Fili.

A few tips:

• The search for the text is case-sensitive. So 'Accept' is not the same as 'accept'.
• If clicking on the background of the cookie interstitial is enough to accept the cookie notification, often 'div' with a few select sequential words from the notification text will work.
• This experimental feature tries to find the HTML element with a partial match for the text provided. If no HTML element is provided, the tool will try to find the text only and as a partial match anywhere within the page and click on the first occurance it finds. For example, the word "ok" will match as a partial match with the word "looking" in a paragraph. So in order for this experimental feature to work, the combination needs to be unique on the page, as in the only HTML element with this specific text nested in its tree. If the most direct element does not provide a unique combination, try one a level up, e.g instead of "a" and "OK" try "div" and "OK".
• You can also click away other type of interstitials, such as newsletter popups. For example, use 'X' or 'Close' as text and select the correct HTML element.
• If the cookie interstitial has a close function (without clicking on the accept or reject button or link), it is possible to target this instead. See previous point.
• If the interstitial is not disappearing with the settings submitted, the HTML element and/or text is probably incorrect or not unique. Try again with an unique combination of a HTML element and text.
• All requests are made from the USA, so if the interstitial changes because of geo specific content, make sure to use the relevant data for US visitors. Alternatively, utilize the Country setting to change to the relevant country instead.

As this feature is highly experimental there are no guarantees it will work in your situation, however contact Fili to provide the feedback.

How to test Cumulative Layout Shift from different countries?

With the Cumulative Layout Shift Debugger it is possible to check the Cumulative Layout Shift from countries other than the United States, and simulate the geographic location of a real user.

To utilize the experimental feature, fill in the URL.

Next, select a country (default is the data center in the United States) and click the green "Check CLS" button.

Currently only a handful of countries are available and as this feature is highly experimental there are no guarantees it will work in your situation, however contact Fili to provide feedback.

How long does it take to generate a Cumulative Layout Shift report?

The test will take several minutes to complete, this is because:

• The Cumulative Layout Shift debugger will try to download the URL you submit, follow any redirect and try to test the final destination on both desktop and mobile emulated devices.
• If the Cumulative Layout Shift score is zero, the Cumulative Layout Shift debugger will attempt to test several times before finalizing the report. Each attempt can take up to two minutes.
• If the HTML code of the webpage changes a lot after the page is loaded, e.g. because of deferred javascript, it will take up to two minutes for a single test to complete.
• The Cumulative Layout Shift debugger will also attempt to query the Chrome User Experience Report to check the stats there for the specific final destination and the relevant hostname, as these numbers may differ and may impact the Google rankings.
• Depending on the number of shifts, it can take up to 30 seconds per emulated device to generate a Cumulative Layout Shift animation with all the shifting elements.

Please be patient, and just keep the loading page open until the report appears (the loading page checks every 5 seconds if the results are finished). If you still encounter a problem, contact Fili.

Why does the Cumulative Layout Shift Debugger not load my URL?

There are several reasons why the Cumulative Layout Shift Debugger is unable to access the URL you provided. For example:

• Firewalls may be blocking requests originating from Google Cloud IP addresses;
• The website does not render within 30 seconds;
• The domain name does not resolve or the scheme is wrong (http vs https);
• The SSL certificate is invalid or self-signed;
• The webpage is flagged as dangerous, like phishing or malware, and blocked from loading in modern browsers;
• The page may be blocked due to geo- and/or language based restrictions implemented on the server side.

Any, or a combination, of the potential reasons mentioned above may be the cause why an URL is inaccessible for the Cumulative Layout Shift Debugger.

Doublecheck the URL again for any potential mistakes and/or misspellings, make sure the website loads within 30 seconds and try to whitelist any request (even if just temporary) coming with the string "webvitals.dev" as part of the User Agent String.

What is a good Cumulative Layout Shift score?

Google considers any Cumulative Layout Shift score below 0.1 to be OK or acceptable for the user experience, and although any Cumulative Layout Shift score between 0.01 and 0.1 can always be futher improved no immediate action is required.

Does this Cumulative Layout Shift tool use the new maximum session window metric?

Yes, the Cumulative Layout Shift Debugger uses the newly defined maximum session window metric, with 1 second gap, capped at 5 seconds. Ofcourse the Cumulative Layout Shift Debugger is a lab-only recording and may not completely cover all user-recording experiences.

Why does the Cumulative Layout Shift score needs improvement?

Google considers any Cumulative Layout Shift score between 0.1 and 0.25 to be in need of improvement, however depending on the individual movements (shifts of elements within the viewport) the priority is lower than a poor score.

Tip: Try to focus on improving the orange and/or red rectangles in the Cumulative Layout Shift animation as the highest priority to fix and then check the Cumulative Layout Shift score again.

What is a poor Cumulative Layout Shift score?

Google considers any Cumulative Layout Shift score above 0.25 to be a poor score, something that requires urgent attention to be addressed, as this translates to a lot of movement (shifts of elements within the viewport) on the page and provides a poor user experience.

What are the green, orange and red rectangles moving in the animations?

The rectangles in the Cumulative Layout Shift animation are representative for the elements moving (shifting in slow-motion) while the webpage is being loaded in the viewport is shown in the animations. Each moving (shifting) element has a Cumulative Layout Shift score associated with it and depending on the severity of the movement (Cumulative Layout Shift) the rectangle is color-coded as green (below 0.1 or acceptable), orange (between 0.1 and 0.25, or needs improvement) and red (above 0.25 or poor user experience).

What is the score in the top left corner of the animation?

The Cumulative Layout Shift score in the top left corner is the aggregated total Cumulative Layout Shift score of the entire webpage, as loaded within the viewport. If there is one Cumulative Layout Shift score for the webpage to consider, this is it.

Can the Cumulative Layout Shift report be shared with third parties?

Yes, the link for the Cumulative Layout Shift report is shareable with anyone up to 31 days after generating it. Also the Cumulative Layout Shift animations can be downloaded and saved to locally by right-click and choose "Save image as", or click on the animation and hitting "Ctrl-S" on the keyboard.

How to use the data and animations?

Try to improve the Cumulative Layout Shift score of the webpage. Based on the Cumulative Layout Shift animation in the report, focus on identifying in the webpage code what is causing the shifts, pay special attention to the orange and/or red rectangles if any and aim at fixing these first. See also the HTML elements in the table underneath the animation. If you don't know how, talk to your developer and show them this report. You can share the link from this report up to 31 days after generation.

The Cumulative Layout Shift score is zero, now what?

Either congratulations are in order, or while fetching and rendering the webpage one or more of the known issues have impacted the Cumulative Layout Shift score.

Identifying the Cumumlative Layout Shift Debugger requests

The Cumulative Layout Shift Debugger is build upon Google Cloud Run using Ubuntu, Debian, Docker, Python 3, Pillow, Playwright Python, aiohttp and Flask.

The Cumulative Layout Shift Debugger is by default fetching webpages from a data center in the USA and is configured to emulate real user sessions by initiating normal browser sessions from different IP addresses worldwide. This process is executed thoughtfully, checking only a few URLs at a time, and does not entail the crawling of significant parts of any website or sending many HTTP requests during an extended period of time. This approach aims to maintain a balanced and responsible interaction with online resources while providing answers to those testing the URLs in question.

Due to this emulation technique and the global distribution of IP addresses, the Cumulative Layout Shift Debugger does not operate within a fixed or predefined range of IP addresses. Instead, the Cumulative Layout Shift Debugger dynamically adapts, based on user input, to various locations and IP configurations. However, the browser sessions generated by the Cumulative Layout Shift Debugger - and the other tools on this website - can easily be identified in the HTTP Header User Agent, which ends with - webvitals.dev and the HTTP Header X-Request-ID, where the value starts with webvitals.

Disclaimer

Every line of code for the Cumulative Layout Shift Debugger is written by SEO expert and ex-Google engineer Fili for free use on this website. The Cumulative Layout Shift Debugger is under constant development and improvements will be added over time.

Bugs will happen. Despite best efforts to maintain the code base and data quality, no guarantees can or will be given. Data may be incomplete and/or errors may occur. This is a personal website and for-fun project. Use at your own risk.