Evolving Cumulative Layout Shift in web tooling

CLS gets a new definition across Chrome's performance tools

Cumulative Layout Shift (CLS) has been a useful signal for encouraging developers to reserve space for images, ads, and other content that can push elements around the viewport. But its original formulation had a problem: because it sums every shift over the entire life of a page, long-lived pages—single-page apps, infinite scroll feeds—accumulated higher scores simply by existing longer. That made comparisons across pages with different session durations unfair.

To address this, Chrome is rolling out a revised CLS definition across Lighthouse, PageSpeed Insights, and the Chrome UX Report (CrUX). The updated metric uses a maximum session window with a 1-second gap, capped at 5 seconds, which was first announced in Evolving the CLS metric. In practice, this means that instead of summing every shift for the entire page lifetime, the metric identifies the worst burst of shifts within that window. The change should be seamless for most sites: 70% of origins will see no change at the 75th percentile, and the remaining 30% will see an improvement.

What changes where

The windowing adjustment is now live in Lighthouse, PageSpeed Insights, and CrUX. Chrome DevTools will follow shortly, and Search Console reflects the change starting June 1, 2021. A summary of what's changed and which tools still expose the original implementation:

Keeping the old definition around

While the new definition is the default, the original "old CLS"—which measures over the full page lifetime—is still accessible in Lighthouse and CrUX for those who want to monitor both:

• In Lighthouse v8, it is available in the JSON output as audits['cumulative-layout-shift'].details.items[0].totalCumulativeLayoutShift.
• In the CrUX API, it appears as experimental_uncapped_cumulative_layout_shift.
• In CrUX BigQuery, it appears as experimental.uncapped_cumulative_layout_shift.

CrUX API requests will return the old metric after June 1:

{
  "origin": "https://web.dev",
  "metrics": [
    "experimental_uncapped_cumulative_layout_shift"
  ]
}

CrUX BigQuery will provide a comparison of old and new CLS after June 8:

WITH
  new_data AS (
  SELECT
    cls
  FROM
    `chrome-ux-report.all.202105`,
    UNNEST(layout_instability.cumulative_layout_shift.histogram.bin) AS cls
  WHERE
    origin = 'https://web.dev'
    AND effective_connection_type.name = '4G'
    AND form_factor.name = 'phone'),
  old_data AS (
  SELECT
    uncapped_cls
  FROM
    `chrome-ux-report.all.202105`,
    UNNEST(experimental.uncapped_cumulative_layout_shift.histogram.bin) AS uncapped_cls
  WHERE
    origin = 'https://web.dev'
    AND effective_connection_type.name = '4G'
    AND form_factor.name = 'phone')
SELECT
  cls.start AS start,
  cls.`END` AS `end`,
  cls.density AS cls_density,
  uncapped_cls.density AS uncapped_cls_density
FROM
  new_data
INNER JOIN
  old_data
ON
  new_data.cls.start = old_data.uncapped_cls.start

These legacy fields will be supported for up to six months, with retirement scheduled for December 14, 2021.

CLS carries more weight in Lighthouse

When CLS was first added to Lighthouse, it was intentionally weighted lightly (5%) so developers could get familiar with it before it affected scores heavily. With the metric now well understood and refined, Lighthouse v8 increases CLS's contribution to the performance score from 5% to 15%, aligning it with the methodology that Core Web Vitals should dominate the score.

This weight change, along with the overall scoring adjustments in Lighthouse v8, can be explored in the scoring calculator.

Lighthouse 8.0 also includes CLS contributions from subframes, which were previously excluded. Field CLS in CrUX was already handling subframe shifts. One remaining difference between lab and field CLS is that the lab measurement window ends at "fully loaded" under lab conditions, while field measurements extend across the entire page lifetime, including any post-load activity. The windowing adjustment narrows this gap considerably.

Measuring the new CLS in the field

To record the updated CLS for your own field data, the PerformanceObserver snippet has been updated, as has the Web Vitals JavaScript library.

Related metric updates

Alongside the CLS change, two other tooling updates are rolling out:

• The latest definition of Largest Contentful Paint is being adopted. CrUX API, PSI, PSI API, and Search Console pick this up on June 1, 2021; CrUX BigQuery updates on June 8, 2021.
• First Contentful Paint tri-binning thresholds in CrUX now use: Good at [0–1.8s], Needs Improvement at (1.8s–3s), and Poor at [3s–∞].

Reviewing your stability scores

Most developers should see no disruption from this rollout. For guidance on diagnosing and reducing layout shifts, see the optimize CLS guidance, and direct any metric feedback to the web-vitals-feedback group or the Lighthouse and Chrome UX Report forums.