Cumulative Layout Shift (CLS)
A metric that measures the visual stability of a web page.
Detailed Explanation
CLS quantifies how often users experience unexpected layout shifts (e.g., a button moving just as you're about to click it). It is caused by images without dimensions, late-loading fonts, or dynamically injected content. A good CLS score is below 0.1. Fixing CLS typically involves reserving space for UI elements before they load and avoiding inserting content above existing content.
Quick Summary
CLS measures how much your page jumps around while loading. A good score (under 0.1) means content stays put as it appears; a bad score means users click the wrong thing because the page shifted under their finger.
Key Takeaways
- Calculated as impact fraction × distance fraction, summed across unexpected shifts during the page lifecycle.
- Top causes: images without dimensions, web fonts swapping, ads/embeds inserted dynamically, late-loading components above-the-fold.
- Excludes user-initiated shifts (clicks, scrolls) for 500ms after the interaction.
- Target: under 0.1 at the 75th percentile of users.
- Reserving space (aspect-ratio CSS, explicit width/height on images, skeleton loaders) is the primary fix.
When to use it
- Media-heavy pages (news, blogs) where images and ads dominate the layout.
- Pages with dynamic embeds (tweets, YouTube, third-party widgets).
- Apps with hydration mismatches between SSR HTML and client React.
- Marketing pages where late-loading hero images push down the CTA.
Common Mistakes
- Omitting `width` and `height` on `<img>` and `<video>`, single biggest cause of CLS in the wild.
- Using `font-display: swap` without `size-adjust` or font matchers, text reflows when the web font loads.
- Injecting cookie banners or notification bars after first paint, pushing content down.
- Measuring CLS only at page load; the metric spans the whole page lifetime, including post-interaction shifts.
Cumulative Layout Shift (CLS), Frequently Asked
How do I fix image-induced CLS?
Set explicit `width` and `height` attributes on `<img>` (browsers derive aspect-ratio automatically and reserve space). For responsive images, also set CSS `aspect-ratio` or `height: auto` to keep proportions correct.
Does CLS apply to single-page apps after navigation?
Yes, it measures shifts throughout the page session, including after route changes. Reserve space for content above the fold on every "page" transition, not just initial load.