Layout Instability API

Draft Community Group Report,

This version:
https://wicg.github.io/layout-instability/
Issue Tracking:
GitHub
Editor:
(Google)
Former Editors:
(Google)
(Google)
(Google)
Not Ready For Implementation

This spec is not yet ready for implementation. It exists in this repository to record the ideas and promote discussion.

Before attempting to implement this spec, please contact the editors.


Abstract

This document defines an API that provides web page authors with insights into the stability of their pages based on movements of the elements on the page.

Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

1. Introduction

This section is non-normative.

The shifting of DOM elements on a webpage detracts from the user’s experience, and occurs frequently on the web today. This shifting is often due to content loading asynchronously and displacing other elements on the page.

The Layout Instability API identifies these unstable pages by reporting a value (the "layout shift") for each animation frame in the user’s session. This specification presents a method for a user agent to compute the layout shift value.

The layout shift value is expected to have a general correspondence to the severity of layout instability at a particular time. The method of computing it considers both the area of the region impacted by instability and the distance by which elements on the page are shifted.

The values exposed by this specification are not meant to be used to serve as "layout change observers" for a couple of reasons. First, they are tied to the PerformanceObserver, hence the dispatch of the callbacks can be done lazily by the user agent if it deems this necessary to avoid impacting performance of the site. Second, very small layout shifts can be ignored by the user agent. Thus, it is not advised to rely on this API as a way of running any JavaScript that impacts the user-visible behavior of a website.

1.1. Cumulative Layout Shift (CLS)

This section is non-normative.

The layout shift value describes one animation frame. Cumulative Layout Shift (CLS) describes the largest burst of unexpected layout shifts during the lifetime of a page. These scores are computed from the LayoutShift entries this specification exposes, but are not themselves exposed by the API.

Only entries whose hadRecentInput is false contribute to the score. Process those entries in order of their startTime, rather than the time the observer callback runs.

A layout shift session window starts with the first eligible shift. Each later eligible shift joins the current window if it occurs less than 1,000 milliseconds after the previous eligible shift and less than 5,000 milliseconds after the first shift in that window. Otherwise, it starts a new window. A gap of exactly 1,000 milliseconds, or a shift exactly 5,000 milliseconds after the first shift, starts a new window. Excluded entries do not extend a window. The score of a window is the sum of its contributing layout shift values.

For example, shifts with values 0.1 and 0.2 at 100 and 600 milliseconds form a window with score 0.3. A shift with value 0.25 at 1,600 milliseconds starts a new window, so the score remains 0.3 rather than increasing to 0.55. Keep the largest window score as later shifts arrive.

A PerformanceObserver in one document does not receive the entries from its child frames, so the usage example computes DCLS for the observed document. Computing CLS needs the weighted shifts from the descendant contexts too. Adding the largest scores from separate documents would combine windows that might have occurred at different times.

Report the largest score seen so far on visibilitychange when the document becomes hidden, after processing any pending observer records. If the user returns to the page, continue observing and report again when it becomes hidden next. The example illustrates windowing, rather than every part of a production measurement. Page lifecycle handling, including starting a new measurement after restoration from the back/forward cache, is described in the CLS measurement guidance.

1.2. Source attribution

This section is non-normative.

In addition to the layout shift value, the API reports a sampling of up to five DOM elements whose layout shifts most substantially contributed to the layout shift value for an animation frame. The sources are sorted by impact area in descending order, so the first element represents the element that contributed most to the layout shift.

It is possible that the true "root cause" of instability will be only indirectly related to the DOM element that experiences a layout shift. For example, if a newly inserted element shifts content below it, the sources attribute will report only the shifted elements, and not the inserted element.

We do not believe it is feasible for the user agent to understand causes of instability at the level of indirection necessary for a meaningful "root cause" attribution. However, we expect that the more straightforward reporting of shifted elements presented in this API will nevertheless be of significant value to developers who are attempting to diagnose an occurrence of layout instability.

1.3. Usage example

This section is non-normative.

let perFrameLayoutShiftData = [];
let documentCumulativeLayoutShiftScore = 0;
let sessionScore = 0;
let sessionStartTime;
let previousShiftTime;

function updateDCLS(entries) {
  for (const entry of entries) {
    // Only count layout shifts without recent user input.
    if (entry.hadRecentInput)
      continue;

    perFrameLayoutShiftData.push({
      score: entry.value,
      timestamp: entry.startTime
    });
    if (previousShiftTime !== undefined &&
        entry.startTime - previousShiftTime < 1000 &&
        entry.startTime - sessionStartTime < 5000) {
      sessionScore += entry.value;
    } else {
      sessionScore = entry.value;
      sessionStartTime = entry.startTime;
    }
    previousShiftTime = entry.startTime;
    documentCumulativeLayoutShiftScore = Math.max(
      documentCumulativeLayoutShiftScore, sessionScore);

    // Sources are sorted by impact area in descending order.
    // The first element contributed most to the layout shift.
    if (entry.sources && entry.sources.length > 0) {
      console.log('Largest contributing element:', entry.sources[0].node);
    }
  }
}

// Observe all layout shift occurrences.
const observer = new PerformanceObserver((list) => {
  updateDCLS(list.getEntries());
});
observer.observe({type: 'layout-shift', buffered: true});

// Report the current score each time the page becomes hidden.
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') {
    // Force any pending records to be dispatched.
    updateDCLS(observer.takeRecords());

    // Send data to your analytics back end (assumes `sendToAnalytics` is
    // defined elsewhere).
    sendToAnalytics({perFrameLayoutShiftData, documentCumulativeLayoutShiftScore});
  }
});

The layout shift score is only one signal, which correlates in an approximate manner with the user experience of "jumpiness".

Developers are advised not to worry about small variations between layout shift scores; this metric is not intended to be a high-precision value, and user agents might compromise precision in the interest of calculation efficiency. Moreover, the definition of the metric might evolve over time.

2. Terminology

2.1. Basic Concepts

The starting point of a Node N in a coordinate space C is defined as follows:

The transform-indifferent starting point of a Node N in a coordinate space C is the starting point of N in C, calculated as if every transformed element had a transformation matrix equal to the identity matrix.

NOTE: To determine whether a node has shifted, we consider the starting point both with and without transforms, to ensure that a node is not made unstable solely due to a transform change. However, the CSS transform is always taken into account for the calculation of the visual representation and the associated exclusion of points outside of the viewport.

The visual representation of a Node N is defined as follows:

A condition holds in the previous frame if it was true at the point in time immediately after the most recently completed invocation of the report the layout shift algorithm.

The previous frame starting point of a Node N in a coordinate space C is the point which, in the previous frame, was the starting point of N in C.

The previous frame transform-indifferent starting point of a Node N in a coordinate space C is the point which, in the previous frame, was the transform-indifferent starting point of N in C.

The previous frame visual representation of a Node N is the set which, in the previous frame, was the visual representation of N.

Each user agent defines a number of pixels to significance, an integer which is used to compute whether movement is considered as a layout shift. This flexibility is provided so that the user agent can adjust for performance or based on user experience considerations.

Point A differs significantly from point B if A and B differ by number of pixels to significance or more pixel units in either the horizontal or vertical direction.

Note: Chrome has defined number of pixels to significance as 3.

2.2. Unstable Nodes

A Node N has shifted in a coordinate space C if:

Otherwise, N has not shifted in C.

A Node N is an unstable-candidate if:

NOTE: The condition relating to a scrollable overflow region is intended to prevent nodes from being considered unstable solely because of a scroll operation.

A Node N is unstable if it is an unstable-candidate and it is not an inline clip crosser.

A Node N is an inline clip crosser if:

NOTE: An example of an inline clip crosser is an element that shifts into or out of view by moving in the inline direction across the boundary of a containing clip. We exclude such an element from the unstable node set as long as it doesn’t shift in the block flow direction. This can make it easier to build certain types of "carousel" user interface controls.

The unstable node set of a Document D is the set containing every unstable shadow-including descendant of D.

NOTE: In the first frame, the previous frame starting point does not exist for any node, and therefore the unstable node set is empty.

2.3. Layout Shift Value

The viewport base distance is the greater of the visual viewport width and the visual viewport height.

The move vector of a Node N is the two-dimensional offset in pixel units from

The move distance of a Node N is the greater of

The maximum move distance of a Document D is the greatest move distance of any Node in the unstable node set of D, or 0 if the unstable node set of D is empty.

The distance fraction of a Document D is the lesser of

The node impact region of an unstable Node N is the set containing

The impact region of a Document D is the set containing every point in the node impact region of any Node in the unstable node set of D.

The impact fraction of a Document D is the area of the impact region divided by the area of the viewport (or 0 if the area of the viewport is 0).

NOTE: Computing the area of the impact region is an instance of the Klee measure problem in two dimensions. A solution using a sweep line and a segment tree, with time complexity O(n lg n) for n unstable nodes, is described here.

The layout shift value of a Document D is the impact fraction of D multiplied by the distance fraction of D.

NOTE: The layout shift value takes into account both the fraction of the viewport that has been impacted by layout instability as well as the greatest distance by which any given element has moved. This recognizes that a large element which moves only a small distance can have a low impact on the perceived instability of the page.

2.4. Input Exclusion

An excluding input is any event from an input device which signals a user’s active interaction with the document, or any event which directly changes the size of the viewport.

Excluding inputs generally include mousedown, keydown, pointerdown, and change events. However, an event whose only effect is to begin or update a flick or scroll gesture is not an excluding input.

The user agent may delay the reporting of layout shifts after a pointerdown event until such time as it is known that the event does not begin a flick or scroll gesture.

The mousemove and pointermove events are also not excluding inputs.

3. LayoutShift interface

[Exposed=Window]
interface LayoutShift : PerformanceEntry {
  readonly attribute double value;
  readonly attribute boolean hadRecentInput;
  readonly attribute DOMHighResTimeStamp lastInputTime;
  readonly attribute FrozenArray<LayoutShiftAttribution> sources;
  [Default] object toJSON();
};

All attributes have the values which are assigned to them by the steps to report the layout shift.

The value attribute returns the layout shift value.

The hadRecentInput attribute returns whether an excluding input occurred recently.

The lastInputTime attribute returns the time of the most recent excluding input.

The sources attribute returns a FrozenArray of LayoutShiftAttribution objects, sorted in descending order by impact area. The first element has the largest node impact region and represents the element that contributed most to the layout shift.

A user agent implementing the Layout Instability API must include "layout-shift" in supportedEntryTypes for Window contexts. This allows developers to detect support for the Layout Instability API.

4. LayoutShiftAttribution interface

[Exposed=Window]
interface LayoutShiftAttribution {
  readonly attribute Node? node;
  readonly attribute DOMRectReadOnly previousRect;
  readonly attribute DOMRectReadOnly currentRect;
};

NOTE: The previousRect and currentRect attributes report rectangles in CSS pixels, consistent with other Web Platform APIs such as getBoundingClientRect(), IntersectionObserver, and ResizeObserver. This provides a device-independent coordinate system that simplifies correlation of layout shift measurements with other DOM measurements.

Each LayoutShiftAttribution is associated with a Node (its associated node).

The node attribute’s getter must perform the following steps:

  1. If this’s associated node is not exposed for paint timing given null, return null.

  2. Return this’s associated node.

Note: Checking whether the node is exposed for paint timing ensures that the node attribute is null if the attributed node is no longer connected, or is inside a shadow root.

The previousRect and currentRect attributes have the values which are assigned to them by the steps to create the attribution.

5. Processing model

Within the update the rendering step of the event loop processing model, a user agent implementing the Layout Instability API MUST perform the following step after the step that invokes the mark paint timing algorithm:

  1. For each fully active Document in docs, invoke the algorithm to report the layout shift for that Document.

5.1. Report the layout shift

When asked to report the layout shift for a fully active Document D, run the following steps:
  1. If the current layout shift value of D is not 0:

    1. Create a new LayoutShift object newEntry with D’s relevant realm.

    2. Set newEntry’s name attribute to the empty string.

    3. Set newEntry’s entryType attribute to "layout-shift".

    4. Set newEntry’s startTime attribute to current high resolution time given D’s relevant global object.

    5. Set newEntry’s duration attribute to 0.

    6. Set newEntry’s value attribute to the current layout shift value of D.

    7. Set newEntry’s lastInputTime attribute to the time of the most recent excluding input, or 0 if no excluding input has occurred during the browsing session.

    8. Set newEntry’s hadRecentInput attribute to true if lastInputTime is less than 500 milliseconds in the past, and false otherwise.

    9. Set newEntry’s sources attribute to the result of invoking the algorithm to report the layout shift sources for D.

    10. Queue the PerformanceEntry newEntry object.

5.2. Report the layout shift sources

When asked to report the layout shift sources for a fully active Document D, run the following steps:
  1. Let C be an empty list of Node objects.

  2. For each member N of the unstable node set of D, run these steps:

    1. If there exists any member existingNode of C such that the node impact region of N is a subset of the node impact region of existingNode, then continue.

    2. Otherwise, if there exists any member existingNode of C such that the node impact region of existingNode is a subset of the node impact region of N, then replace the first such member existingNode with N in C.

    3. Otherwise, if there are fewer than 5 members of C, then append N to C.

      NOTE: The choice of 5 is arbitrary but it balances providing detailed attribution while not having a prohibitive memory cost or being spammy in the set of nodes exposed.

    4. Otherwise, run these steps:

      1. Let smallest be the first member of C whose node impact region is not greater in area than the node impact region of any other member of C.

      2. If the area of the node impact region of N is greater than the area of the node impact region of smallest, then replace smallest with N in C.

  3. Sort C in descending order, with a being less than b if the area of the node impact region of a is less than the area of the node impact region of b.

    NOTE: This ensures that the sources attribute exposes layout shift sources in descending order by impact area, with the element that contributed most to the layout shift appearing first.

  4. Return a FrozenArray of LayoutShiftAttribution objects created by running the algorithm to create the attribution once for each member of C.

When asked to create the attribution for a Node N, run the following steps:
  1. Create a new LayoutShiftAttribution object A with N’s relevant realm.

  2. Set the associated node of A to N.

  3. Set the previousRect attribute of A to the smallest rectangle containing the previous frame visual representation of N, in CSS pixels.

  4. Set the currentRect attribute of A to the smallest rectangle containing the visual representation of N, in CSS pixels.

  5. Return A.

6. Security & privacy considerations

Layout instability bears an indirect relationship to [RESOURCE-TIMING], as slow resources could cause intermediate layouts that would not otherwise be performed. Resource timing information can be used by malicious websites for statistical fingerprinting. The Layout Instability API only reports instability in the current browsing context. It does not directly provide any aggregation of instability scores across multiple browsing contexts. Developers can implement such aggregation manually, but browsing contexts with different origins would need to cooperate to share instability scores.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-BREAK-4]
Rossen Atanassov; Elika Etemad. CSS Fragmentation Module Level 4. URL: https://drafts.csswg.org/css-break-4/
[CSS-CASCADE-5]
Elika Etemad; Miriam Suzanne; Tab Atkins Jr.. CSS Cascading and Inheritance Level 5. URL: https://drafts.csswg.org/css-cascade-5/
[CSS-COLOR-4]
Tab Atkins Jr.; Chris Lilley; Lea Verou. CSS Color Module Level 4. URL: https://drafts.csswg.org/css-color-4/
[CSS-DISPLAY-4]
Elika Etemad; Tab Atkins Jr.. CSS Display Module Level 4. URL: https://drafts.csswg.org/css-display-4/
[CSS-INLINE-3]
Elika Etemad. CSS Inline Layout Module Level 3. URL: https://drafts.csswg.org/css-inline-3/
[CSS-OVERFLOW-3]
Elika Etemad; Florian Rivoal. CSS Overflow Module Level 3. URL: https://drafts.csswg.org/css-overflow-3/
[CSS-TRANSFORMS-1]
Simon Fraser; et al. CSS Transforms Module Level 1. URL: https://drafts.csswg.org/css-transforms/
[CSS-VALUES-4]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 4. URL: https://drafts.csswg.org/css-values-4/
[CSS-WRITING-MODES-4]
Elika Etemad; Koji Ishii. CSS Writing Modes Level 4. URL: https://drafts.csswg.org/css-writing-modes-4/
[CSSOM-VIEW-1]
Simon Fraser; Emilio Cobos Álvarez. CSSOM View Module. URL: https://drafts.csswg.org/cssom-view/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[GEOMETRY-1]
Sebastian Zartner; Yehonatan Daniv. Geometry Interfaces Module Level 1. URL: https://drafts.csswg.org/geometry/
[HR-TIME-3]
Yoav Weiss. High Resolution Time. URL: https://w3c.github.io/hr-time/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[PAINT-TIMING]
Ian Clelland; Noam Rosenthal. Paint Timing. URL: https://w3c.github.io/paint-timing/
[PERFORMANCE-TIMELINE]
Nicolas Pena Moreno. Performance Timeline. URL: https://w3c.github.io/performance-timeline/
[POINTEREVENTS3]
Patrick Lauke; Robert Flack. Pointer Events. URL: https://w3c.github.io/pointerevents/
[RESOURCE-TIMING]
Yoav Weiss; Noam Rosenthal. Resource Timing. URL: https://w3c.github.io/resource-timing/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[UIEVENTS]
Xiaoqian Wu. UI Events. URL: https://w3c.github.io/uievents/
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/

Non-Normative References

[INTERSECTION-OBSERVER]
Stefan Zager; Emilio Cobos Álvarez; Traian Captan. Intersection Observer. URL: https://w3c.github.io/IntersectionObserver/
[RESIZE-OBSERVER-1]
Aleks Totic; Greg Whitworth. Resize Observer. URL: https://drafts.csswg.org/resize-observer/

IDL Index

[Exposed=Window]
interface LayoutShift : PerformanceEntry {
  readonly attribute double value;
  readonly attribute boolean hadRecentInput;
  readonly attribute DOMHighResTimeStamp lastInputTime;
  readonly attribute FrozenArray<LayoutShiftAttribution> sources;
  [Default] object toJSON();
};

[Exposed=Window]
interface LayoutShiftAttribution {
  readonly attribute Node? node;
  readonly attribute DOMRectReadOnly previousRect;
  readonly attribute DOMRectReadOnly currentRect;
};