LargestContentfulPaint
======================

The `LargestContentfulPaint` interface provides timing information about the largest image or text paint before user input on a web page.

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

The key moment this API provides is the Largest Contentful Paint (LCP) metric. It provides the render time of the largest image or text block visible within the viewport, recorded from when the page first begins to load. The following elements are considered when determining the LCP:

* `<img>` elements.
* `<image>` elements inside an SVG.
* The poster images of `<video>` elements.
* Elements with a `background-image`.
* Groups of text nodes, such as `<p>`.

To measure render times of other elements, use the `PerformanceElementTiming` API.

Additional key paint moments are provided by the `PerformancePaintTiming` API:

* First paint (FP): Time when anything is rendered. Note that the marking of the first paint is optional, not all user agents report it.
* First contentful paint (FCP): Time when the first bit of DOM text or image content is rendered.

`LargestContentfulPaint` inherits from `PerformanceEntry`.

PerformanceEntry

LargestContentfulPaintInstance properties
-------------------

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

`PerformanceEntry.entryType` Read only  
Experimental

Returns "`largest-contentful-paint`".

`PerformanceEntry.name` Read only  
Experimental

Always returns an empty string.

`PerformanceEntry.startTime` Read only  
Experimental

Returns the value of this entry's `renderTime` if it is not `0`, otherwise the value of this entry's `loadTime`.

`PerformanceEntry.duration` Read only  
Experimental

Returns `0`, as `duration` is not applicable to this interface.

It also supports the following properties:

`LargestContentfulPaint.element` Read only 

The element that is the current largest contentful paint.

`LargestContentfulPaint.renderTime` Read only 

The time the element was rendered to the screen. May not be available if the element is a cross-origin image loaded without the `Timing-Allow-Origin` header.

`LargestContentfulPaint.loadTime` Read only 

The time the element was loaded.

`LargestContentfulPaint.size` Read only 

The intrinsic size of the element returned as the area (width \* height).

`LargestContentfulPaint.id` Read only 

The id of the element. This property returns an empty string when there is no id.

`LargestContentfulPaint.url` Read only 

If the element is an image, the request url of the image.

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

*This interface also inherits methods from `PerformanceEntry`.*

`LargestContentfulPaint.toJSON()`

Returns a JSON representation of the `LargestContentfulPaint` object.

Examples
--------

### Observing the largest contentful paint

In the following example, an observer is registered to get the largest contentful paint while the page is loading. The `buffered` flag is used to access data from before observer creation.

The LCP API analyzes all content it finds (including content that is removed from the DOM). When new largest content is found, it creates a new entry. It stops searching for larger content when scroll or input events occur, since these events likely introduce new content on the website. Thus the LCP is the last performance entry reported by the observer.


```js
const observer = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  const lastEntry = entries[entries.length - 1]; // Use the latest LCP candidate
  console.log("LCP:", lastEntry.startTime);
  console.log(lastEntry);
});
observer.observe({ type: "largest-contentful-paint", buffered: true });
```

### Cross-origin image render time

For security reasons, the value of the `renderTime` property is `0` if the resource is a cross-origin request. Instead the `loadTime` is exposed. To expose cross-origin render time information, the `Timing-Allow-Origin` HTTP response header needs to be set.

For example, to allow `https://developer.mozilla.org` to see `renderTime`, the cross-origin resource should send:


```http
Timing-Allow-Origin: https://developer.mozilla.org
```


Like in the code example, you can use `startTime`, which returns the value of the entry's `renderTime` if it is not `0`, and otherwise the value of this entry's `loadTime`. However, it is recommended to set the `Timing-Allow-Origin` header so that the metrics will be more accurate.

If you use `startTime`, you can flag any inaccuracies by checking if `renderTime` was used:


```js
const isAccurateLCP = entry.renderTime ? true : false;
```

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

| Specification |
| --- |
| Largest Contentful Paint # sec-largest-contentful-paint-interface |

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

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

See also
--------

* Largest Contentful Paint
* First contentful paint
* First paint