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 14 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.
• 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-evaluating 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 aggressive bot blocking rules. If this is a website you own, you can try to whitelist the CLS Debugger. Each HTTP request is made with a unique X-Request-Id (starting with webvitals.cls.) and Referer (starting with https://webvitals.dev/) HTTP header.
• 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.
• The Chromium Layout Instability API 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 separately 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.
• 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.
• 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.
• The Cumulative Layout Shift score is calculated based on viewport size, so likely the scores will be higher for mobile users because the viewports are smaller and the impact of each shift as a percentage is therefore larger.
• Large interstitials (e.g. for cookie acknowledgements) can prevent the Cumulative Layout Shifts from being 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.

Frequently Asked Questions

How to use the experimental cookie interstitial feature?

Keep in mind that using this feature may impact (either positively or negatively) the Cumulative Layout Shift scores. 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: check what type of HTML element this text is located in. Currently only 'button', 'div', 'span' and 'a' are supported.

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. The combination needs to be unique on the page. If the most direct element does not provide a unique combination, try one a level up.
• 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.

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. Select a country from the dropdown and click the "Check CLS score" button.

How long does it take to generate a report?

The test will take several minutes to complete because:

• The CLS debugger follows any redirects and tests the final destination on both desktop and mobile emulated devices.
• If the CLS score is zero, the debugger will attempt to test several times before finalizing the report.
• If the HTML code changes a lot after page load (e.g. deferred JavaScript), it will take up to two minutes for a single test to complete.
• The debugger also queries the Chrome User Experience Report for the specific URL and origin.
• Depending on the number of shifts, it can take up to 30 seconds per emulated device to generate the animation.

Why does the CLS Debugger not load my URL?

There are several reasons why the URL may be inaccessible:

• Firewalls may be blocking requests from our data center IP addresses, which are published at filibot.com.
• 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 (phishing or malware) and blocked.
• The page may be blocked due to geo- and/or language-based restrictions.

Identifying the CLS Debugger requests

The CLS Debugger fetches webpages from data centers and emulates real user sessions by initiating normal browser sessions. These requests come from a published set of IP addresses, listed at filibot.com and available as ips.json for firewall allow-lists. Each request also carries a Referer of https://webvitals.dev/ and an X-Request-ID starting with webvitals.cls.

Please note that although the CLS Debugger shares the same IP addresses as filibot, it approaches your website as a user rather than a bot, so it does not follow robots.txt in this case. To keep it out, block these IP addresses at the firewall level or refrain from submitting the URL.

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.

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. Use at your own risk.