Chapter 3: How to debug Cumulative Layout Shift issues using CSS selectors

Visual stability plays an important role in user experience (UX). One of the most frustrating issues for users is when elements shift around during page load or navigation. And that’s exactly what CLS measures: the largest burst of layout shift scores for every unexpected layout shift that occurs during the entire lifecycle of a page. Or in other words, CLS tracks the most significant unexpected movements on a webpage that occur during your entire visit.

Many Real User Monitoring (RUM) solutions report CSS selectors responsible for poor CLS scores. However, keep in mind that they report the displaced element rather than the element that is actually causing the problem. If you missed the first chapter where we explain what a CSS selector is, you can read it here

Let’s see this in action with an example.

In the screenshot above, you can see that the elements in the filter with icons have experienced some changes: they are now wider and taller. The increased width of each element pushes the elements on its right further to the right. Additionally, the increased height has pushed down the grid component where the products are displayed.

While these Cumulative Layout Shift (CLS) issues can significantly impact user satisfaction, identifying their root causes can often be challenging. Let's explore how to effectively debug these problems by analyzing the CSS selector of nodes that show poor CLS scores.

Setting Up for Debugging Jump to heading #

Like in the LCP analysis, to begin debugging, reproduce the page load conditions by recreating the exact (or very similar) scenario where users experienced poor CLS scores. Locate the CSS selector by navigating to Chrome DevTools > Elements panel and use the search function (Ctrl + F on Windows/Linux or Cmd + F on MacOS) to find your specific selector. It might happen that the webpage element is in the viewport but sometimes it can be below the fold (not visible in the viewport).

Identifying the layout shift Jump to heading #

Once you've identified the problematic element, observe its behavior during page load. If the element is visible in the viewport during loading, you should notice it being displaced either vertically or horizontally by other elements – these are your culprits.

The root cause typically stems from a common CSS mistake: insufficient space reservation for elements that load later in the process. When these late-loading elements finally render at their full size, they relocate previously rendered content (your CSS selector), creating an unwanted layout shift. The solution lies in proper space allocation for these late-rendering elements.

For instance, if an image is pushing your content downward, ensure it has explicitly defined height and width properties, or implement an aspect-ratio property to maintain the correct proportions during loading. This proactive space reservation prevents the layout shifts that frustrate users.

Sometimes your CSS selector might not be immediately visible in the viewport, which can happen for two reasons: either the element was initially visible during loading but got pushed down, or it's an element that was never part of the above-the-fold content. If it's the former, you can follow the debugging process discussed earlier. However, if your selector was never in the above-the-fold content, you're likely dealing with CLS issues during navigation rather than during the initial page load.

To debug navigation-related CLS issues, you'll need to simulate real user behavior. Go to Chrome DevTools > Performance panel and reload the page. After that, since you want to measure the navigation instead of the page load, press the Record button instead of the Record and reload, and scroll or navigate until you spot your CSS selector element. Watch for elements that trigger layout shifts.

Common CLS culprits Jump to heading #

Several common culprits typically cause these shifts:

• Images or videos lacking explicit dimensions. Easily fixed by adding height/width or aspect-ratio properties, as mentioned above.
• Dynamically injected elements appearing after initial content render. Solution: reserve appropriate space using height/width. If the actual size of the injected element is not known in advance, set the minimum space it will be occupied with min-height/min-width properties to reduce the impact as much as possible.
• Problematic animations. Avoid using CSS top/bottom or direct height/width modifications – instead, opt for transform:translateX/Y() and transform:scale() properties for smoother animations.
• Font loading can also trigger layout shifts, particularly when custom fonts render differently than their fallbacks, potentially causing text reflow or unexpected line breaks. To mitigate this, either choose a more closely matched fallback font or create a custom one using tools like the Fallback Font Generator.

See it in action Jump to heading #

Let's explore how debug Cumulative Layout Shift issues by analyzing CSS selectors in a real-world example with Shopify's Performance Reports.

Step 1: Access the CLS report Jump to heading #

Navigate to the "Cumulative Layout Shift: Page Type" report in your Shopify admin. You'll see a breakdown similar to this:

Step 2: Analyze CSS selectors Jump to heading #

In the example above, the Product pages show poor CLS scores. Let's dig deeper to identify which CSS selectors might be causing the layout shifts.

To identify the specific CSS selectors reporting CLS values on Product pages:

1. Under "Dimensions", select "Cumulative Layout Shift target" instead of "Page type"
2. Add a filter for "Page type" and set it to "Product"
3. Add a filter for "Device type" and set it to "Mobile"

This will give you a detailed view of CSS selectors of elements reporting CLS scores, ordered by page load frequency:

Step 3: Find the element with poor CLS scores using the CSS selector Jump to heading #

Load a Product page in Chrome, open Chrome DevTools and search for the CSS selector in the Elements panel:

You can check the reported CLS score for that specific page in your browser by navigating to the Performance panel. If no metrics are displayed initially, try reloading the page.

Step 4: Analize common CLS issues Jump to heading #

Now that we've identified the element experiencing poor CLS scores, we need to determine which elements are causing the layout shifts. There is a comprehensive blog post on how to optimize CLS on Shopify stores that covers all common issues and their solutions.

In this example, the issue is caused by the <header> element, which is client-side rendered without reserved space through CSS.which is client-side rendered without reserved space. To fix this, we can reserve the proper space by explicitly setting its height for the different viewport sizes.

Once the changes were implemented, the CLS scores successfully dropped below the critical threshold of 0.1, ensuring a smoother user experience:

Conclusion Jump to heading #

In this article, we covered how to debug and fix the most common Cumulative Layout Shift (CLS) issues thanks to knowing the CSS selector of the CLS target. You can jump straight into fixing Interaction to Next Paint (INP) issues in Chapter 4, or review how to fix Largest Contentful Paint (LCP) problems in Chapter 2.

Cover hoto by Dominik Mecko on Unsplash