LargestContentfulPaint

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

TheLargestContentfulPaint 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 theLargest 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 abackground-image.
Groups of text nodes, such as<p>.

To measure render times of other elements, use thePerformanceElementTiming API.

Additional key paint moments are provided by thePerformancePaintTiming 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 fromPerformanceEntry.

To get an accurate measurement of render time for cross-origin resources, set theTiming-Allow-Origin header.

Developers should usestartTime instead ofrenderTime as the LCP value, as therenderTime may not be set in some browsers.

SeeCross-origin image render time andUse startTime over renderTime for more details.

Instance properties

This interface extends the followingPerformanceEntry properties by qualifying and constraining the properties as follows:

PerformanceEntry.entryTypeRead onlyExperimental: Returns"largest-contentful-paint".
PerformanceEntry.nameRead onlyExperimental: Always returns an empty string.
PerformanceEntry.startTimeRead onlyExperimental: Returns the value of this entry's renderTime if it is not0, otherwise the value of this entry'sloadTime.
PerformanceEntry.durationRead onlyExperimental: Returns0, asduration is not applicable to this interface.

It also supports the following properties:

LargestContentfulPaint.elementRead only: The element that is the current largest contentful paint.
LargestContentfulPaint.renderTimeRead only: The time the element was rendered to the screen. May be a coarsened value or0 if the element is a cross-origin image loaded without theTiming-Allow-Origin header.
LargestContentfulPaint.loadTimeRead only: The time the element was loaded.
LargestContentfulPaint.sizeRead only: The intrinsic size of the element returned as the area (width * height).
LargestContentfulPaint.idRead only: The id of the element. This property returns an empty string when there is no id.
LargestContentfulPaint.urlRead only: If the element is an image, the request url of the image.

Instance methods

This interface also inherits methods fromPerformanceEntry.

LargestContentfulPaint.toJSON(): Returns a JSON representation of theLargestContentfulPaint 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. Thebuffered 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.

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 });