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.
-
The document cumulative layout shift (DCLS) score is the largest layout shift session window score inside a single browsing context, or zero if there are no eligible shifts. It does not include shifts inside descendant browsing contexts.
-
The cumulative layout shift (CLS) score is the largest layout shift session window score for a top-level browsing context and its descendant browsing contexts, or zero if there are no eligible shifts. Combine the eligible shifts into one timeline, with times expressed relative to the same origin, before forming windows. Each shift in the top-level context contributes its layout shift value. Each shift in a descendant context contributes its layout shift value multiplied by the subframe weighting factor.
-
The subframe weighting factor for a layout shift value in a child browsing context is the fraction of the top-level viewport that is occupied by the viewport of the child browsing context.
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 entryof 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:
-
If N is an
Elementwhich generates one or more boxes, the starting point of N in C is the two-dimensional offset in pixel units from the origin of C to the flow-relative starting corner of the first fragment of the principal box of N. -
If N is a text node, the starting point of N in C is the two-dimensional offset in pixel units from the origin of C to the flow-relative starting corner of the first line box generated by N.
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:
-
If N is an
Elementwhich generates one or more boxes, the visual representation of N is the set of all points that lie within the bounds of any fragment of any box generated by N, in the coordinate space of the viewport, excluding any points that lie outside of the viewport. -
If N is a text node, the visual representation of N is the set of all points that lie within the bounds of any line box generated by N, in the coordinate space of the viewport, excluding any points that lie outside of the viewport.
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:
-
the starting point of N in C differs significantly from the previous frame starting point of N in C, and
-
the transform-indifferent starting point of N in C differs significantly from the previous frame transform-indifferent starting point of N in C.
Otherwise, N has not shifted in C.
A Node N is an unstable-candidate if:
-
N is either
-
currently and in the previous frame, the computed value of the visibility property for N equals visible; and
-
currently and in the previous frame, the computed value of the opacity property for N and for every ancestor of N is not equal to 0; and
-
N has shifted in the coordinate space of the viewport; and
-
N has shifted in the coordinate space of the initial containing block; and
-
there does not exist an
ElementP such that-
currently and in the previous frame, P is in the containing block chain of N, and
-
currently and in the previous frame, P has a scrollable overflow region, and
-
P is not an unstable-candidate, and
-
N has not shifted in the coordinate space of the scrollable overflow region of P.
-
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:
-
N is an unstable-candidate;
-
either the visual representation or the previous frame visual representation of N is empty; and
-
N would not be an unstable-candidate if the phrase "either the horizontal or vertical direction" in the definition of differs significantly were replaced by "the vertical direction" (if the block axis of N is vertical) or "the horizontal direction" (if the block axis of N is horizontal).
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 previous frame starting point of N in the coordinate space of the viewport, to
-
the starting point of N in the coordinate space of the viewport.
The move distance of a Node N is the greater of
-
the absolute value of the horizontal component of the move vector of N, and
-
the absolute value of the vertical component of the move vector of N.
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 maximum move distance of D divided by the viewport base distance (or 0 if the viewport base distance is 0), and
-
1.0.
The node impact region of an unstable Node N
is the set containing
-
every point in the visual representation of N, and
-
every point in the previous frame visual representation of N.
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
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:
-
If this’s associated node is not exposed for paint timing given null, return null.
-
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:
-
For each fully active
Documentin docs, invoke the algorithm to report the layout shift for thatDocument.
5.1. Report the layout shift
Document D, run the following steps:
-
If the current layout shift value of D is not 0:
-
Create a new
LayoutShiftobject newEntry with D’s relevant realm. -
Set newEntry’s
nameattribute to the empty string. -
Set newEntry’s
entryTypeattribute to."layout-shift" -
Set newEntry’s
startTimeattribute to current high resolution time given D’s relevant global object. -
Set newEntry’s
durationattribute to 0. -
Set newEntry’s
valueattribute to the current layout shift value of D. -
Set newEntry’s
lastInputTimeattribute to the time of the most recent excluding input, or 0 if no excluding input has occurred during the browsing session. -
Set newEntry’s
hadRecentInputattribute toiftrue lastInputTimeis less than 500 milliseconds in the past, andotherwise.false -
Set newEntry’s
sourcesattribute to the result of invoking the algorithm to report the layout shift sources for D. -
Queue the PerformanceEntry newEntry object.
-
5.2. Report the layout shift sources
Document D, run the following steps:
-
For each member N of the unstable node set of D, run these steps:
-
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.
-
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.
-
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.
-
Otherwise, run these steps:
-
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.
-
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.
-
-
-
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
sourcesattribute exposes layout shift sources in descending order by impact area, with the element that contributed most to the layout shift appearing first. -
Return a
FrozenArrayofLayoutShiftAttributionobjects created by running the algorithm to create the attribution once for each member of C.
Node N,
run the following steps:
-
Create a new
LayoutShiftAttributionobject A with N’s relevant realm. -
Set the associated node of A to N.
-
Set the
previousRectattribute of A to the smallest rectangle containing the previous frame visual representation of N, in CSS pixels. -
Set the
currentRectattribute of A to the smallest rectangle containing the visual representation of N, in CSS pixels. -
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.