How can you fix something if you don't know what's broken?
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.
The Cumulative Layout Shift Debugger is fetching webpages from the USA and is build upon Google Flexible App Engine using Debian, Docker, Python 3, Pillow, Playwright Python and Flask. In addition, the Chrome User Experience Report data is pulled from the Google Chrome UX Report API for the webpage and relevant hostname in question to provide extra context. During the test the CPU and network are throttled. Currently only Pixel 2 for mobile and a standard desktop (1920x1080) are supported. Report links are accessible, shareable and available for 31 days after generation.
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.
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.
You know, the first step to fixing something is to know no matter how destroyed it seems, it can always be saved.
- 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.
- 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.
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 and click on "Advanced" under the URL field in the form.
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.
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 and click on "Advanced" under the URL field in the form.
Next, select a country (default is the Google Cloud 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.
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.
- 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.
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 is so slow it 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.
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.
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.
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.
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.
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).
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.
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.
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.
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.