LayoutShift
===========

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The `LayoutShift` interface of the Performance API provides insights into the layout stability of web pages based on movements of the elements on the page.

Description
-----------

A layout shift happens when any element that is visible in the viewport changes its position between two frames. These elements are described as being **unstable**, indicating a lack of visual stability.

The Layout Instability API provides a way to measure and report on these layout shifts. All tools for debugging layout shifts, including those in the browser's developer tools, use this API. The API can also be used to observe and debug layout shifts by logging the information to the console, to send the data to a server endpoint, or to web page analytics.

Popular performance tools, use this API to calculate a Cumulative Layout Shift (CLS) score.

PerformanceEntry

LayoutShiftInstance properties
-------------------

This interface extends the following `PerformanceEntry` properties by qualifying them as follows:

`PerformanceEntry.duration` Read only  
Experimental

Always returns `0` (the concept of duration does not apply to layout shifts).

`PerformanceEntry.entryType` Read only  
Experimental

Always returns `"layout-shift"`.

`PerformanceEntry.name` Read only  
Experimental

Always returns `"layout-shift"`.

`PerformanceEntry.startTime` Read only  
Experimental

Returns a `DOMHighResTimeStamp` representing the time when the layout shift started.

This interface also supports the following properties:

`LayoutShift.value` 
Experimental

Returns the layout shift score calculated as the impact fraction (fraction of the viewport that was shifted) multiplied by the distance fraction (distance moved as a fraction of viewport).

`LayoutShift.hadRecentInput` 
Experimental

Returns `true` if `lastInputTime` is less than 500 milliseconds in the past.

`LayoutShift.lastInputTime` 
Experimental

Returns the time of the most recent excluding input (user input that would exclude this entry as a contributor to the CLS score) or `0` if no excluding input has occurred.

`LayoutShift.sources` 
Experimental

Returns an array of `LayoutShiftAttribution` objects with information on the elements that were shifted.

Instance methods
----------------

`LayoutShift.toJSON()` 
Experimental

Converts the properties to JSON.

Examples
--------

### Logging layout shift values

The following example shows how to capture layout shifts and log them to the console.


```js
const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    // Count layout shifts without recent user input only
    if (!entry.hadRecentInput) {
      console.log("LayoutShift value:", entry.value);
      if (entry.sources) {
        for (const { node, currentRect, previousRect } of entry.sources)
          console.log("LayoutShift source:", node, {
            currentRect,
            previousRect,
          });
      }
    }
  }
});

observer.observe({ type: "layout-shift", buffered: true });
```

Specifications
--------------

| Specification |
| --- |
| Layout Instability # sec-layout-shift |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `LayoutShiftAttribution`
* Cumulative Layout Shift (CLS)