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
represents
describes
one
animation
frame.
Cumulative
Layout
Shift
(CLS)
describes
the
largest
burst
of
unexpected
layout
shifts
during
the
lifetime
of
a
single
point
in
time,
page.
These
scores
are
computed
from
the
LayoutShift
entries
this
specification
exposes,
but
it
are
not
themselves
exposed
by
the
API.
Only
entries
whose
hadRecentInput
is
also
useful
to
have
a
value
false
contribute
to
represent
the
total
instability
score.
Process
those
entries
in
order
of
their
startTime
,
rather
than
the
page
for
the
period
of
time
the
user
spends
on
it.
observer
callback
runs.
To
that
end
we
propose
two
values
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
user
agent
new
window.
A
gap
of
exactly
1,000
milliseconds,
or
a
developer
is
able
to
compute
to
obtain
such
a
representation.
(These
definitions
are
non-normative,
because
shift
exactly
5,000
milliseconds
after
the
API
does
first
shift,
starts
a
new
window.
Excluded
entries
do
not
expose
these
values.)
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
sum of everylargest layout shiftvaluesession windowthat is reportedscore inside a single browsing context. (The DCLS score, or zero if there are no eligible shifts. It does notaccount for layout instabilityinclude shifts inside descendant browsingcontexts.)contexts. -
The cumulative layout shift (CLS) score is the
sum of everylargest layout shiftvaluesession windowthat is reported insidescore for a top-level browsing context and its descendant browsing contexts ,plusor 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 afraction (the subframe weighting factor ) of eachdescendant context contributes its layout shift valuethat is reported inside any descendant browsing contextmultiplied 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.
The
cumulative
layout
shift
For
example,
shifts
with
values
0.1
and
0.2
at
100
and
600
milliseconds
form
a
window
with
score
is
expected
to
have
0.3.
A
shift
with
value
0.25
at
1,600
milliseconds
starts
a
general
correspondence
to
new
window,
so
the
severity
of
layout
instability
for
score
remains
0.3
rather
than
increasing
to
0.55.
Keep
the
lifetime
of
a
page.
largest
window
score
as
later
shifts
arrive.
The
developer
can
use
this
API
to
compute
A
PerformanceObserver
in
one
document
does
not
receive
the
entries
from
its
child
frames,
so
the
usage
example
computes
DCLS
or
for
the
observed
document.
Computing
CLS
scores,
by
summing
needs
the
values
as
they
are
reported
to
weighted
shifts
from
the
observer,
and
taking
descendant
contexts
too.
Adding
the
"final"
score
largest
scores
from
separate
documents
would
combine
windows
that
might
have
occurred
at
different
times.
Report
the
time
of
the
largest
score
seen
so
far
on
visibilitychange
event.
This
strategy
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
illustrated
described
in
the
usage
example.
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}); cumulativeLayoutShiftScoreif ( 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) => { updateCLSupdateDCLS( 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. updateCLSupdateDCLS( observer. takeRecords()); // Send data to your analytics back end (assumes `sendToAnalytics` is // defined elsewhere). sendToAnalyticssendToAnalytics({ 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.