Largest Contentful Paint

1. Introduction

This section is non-normative. The LargestContentfulPaint API enables developers to gain visibility into the loading and rendering process of the web pages, in order for them to be able to optimize it.

Developers today don’t have a reliable metric that correlates with their user’s visual rendering experience. Existing metrics such as First Paint and First Contentful Paint focus on initial rendering, but don’t take into account the importance of the painted content, and therefore may indicate times in which the user still does not consider the page useful.

Largest Contentful Paint (LCP) aims to be a new page-load metric that:

• better correlates with user experience than the existing page-load metrics

• is easy to understand and reason about

• reduces the chance of gaming

The largest paint during the loading process of the page is likely to signify a meaningful event from the user’s perspective, and is therefore something we want to expose by default to developers, enabling performance teams, analytics providers and lab-based measurement tools to collect those metrics without requiring extra annotation work by the folks creating the content itself.

The API relies heavily on [ELEMENT-TIMING] , which can be thought of as the low-level primitive that this high-level feature is built on top of. For cases where the content creators are willing to annotate their content and indicate the important points in the page’s loading cycle, Element Timing is the API that will provide them more control over the elements that get reported.

1.1. Elements exposed

The Largest Contentful Paint API will only expose element types that are already exposed by the Element Timing API. In this case, there is no need to annotate them with the elementtiming attribute.

1.2. Largest content

The algorithm used for this API keeps track of the content seen so far. Whenever a new largest content is found, a new entry is created for it. Content that is removed is still considered by the algorithm. In particular, if the content removed was the largest, then a new entry is created only if larger content is ever added. The algorithm terminates whenever scroll or input events occur, since those are likely to introduce new content into the website.

1.3. Usage example

The following example shows an image and a large body of text. The developer then registers an observer that gets candidate entries for the largest paint while the page is loading.

<img src="large_image.jpg">
<p id='large-paragraph'>This is large body of text.</p>
...
<script>
const observer = new PerformanceObserver((list) => {
  let perfEntries = list.getEntries();
  let lastEntry = perfEntries[perfEntries.length - 1];
  // Process the latest candidate for largest contentful paint
});
observer.observe({entryTypes: ['largest-contentful-paint']});
</script>

1.4. Limitations

The LargestContentfulPaint API is based on heuristics. As such, it is error prone. It has the following problems:

• The algorithm halts when it detects certain types of user inputs. However, this means that the algorithm will not capture the main content if the user input occurs before the main content is displayed. In fact, the algorithm may produce meaningless results or no results at all if user input occurs very early.

• To account for image carousels, content is still considered as the largest even if it’s removed. This presents problems for websites with splash screens that use large content as placeholders.

2. Largest Contentful Paint

Largest Contentful Paint involves the following new interface:

2.1. LargestContentfulPaint interface

[Exposed=Window]
interface LargestContentfulPaint : PerformanceEntry {
    readonly attribute DOMHighResTimeStamp renderTime;
    readonly attribute DOMHighResTimeStamp loadTime;
    readonly attribute unsigned long size;
    readonly attribute DOMString id;
    readonly attribute DOMString url;
    readonly attribute Element? element;
    [Default] object toJSON();
};

Each LargestContentfulPaint object has these associated concepts:

• A renderTime , initially set to 0.

• A size , initially set to 0.

• A loadTime , initially set to 0.

• An id , initially set to the empty string.

• A url , initially set to the empty string.

• An element containing the associated Element , initially set to null .

The entryType attribute’s getter must return the DOMString "largest-contentful-paint" .

The name attribute’s getter must return the empty string.

The startTime attribute’s getter must return the value of this ’s renderTime if it is not 0, and the value of this ’s loadTime otherwise.

The duration attribute’s getter must return 0.

The renderTime attribute must return the value of this ’s renderTime .

The loadTime attribute must return the value of this ’s loadTime .

The size attribute must return the value of this ’s size .

The id attribute must return the value of this ’s id .

The url attribute must return the value of this ’s url .

The element attribute’s getter must return the value returned by running the get an element algorithm with element and null as inputs.

Note: The above algorithm defines that an element that is no longer descendant of the Document will no longer be returned by element 's attribute getter, including elements that are inside a shadow DOM.

This specification also extends Document by adding to it a largest contentful paint size concept, initially set to 0. It also adds an associated content set , which is initially an empty set . The content set will be filled with pairs with an Element as the first item and a Request as the second item. This is used for performance, to enable the algorithm to only consider each content once.

Note: The user agent needs to maintain the content set so that removed content does not introduce memory leaks. In particular, it can tie the lifetime of the pairs to weak pointers to the Elements so that it can be cleaned up sometime after the Elements are removed. Since the set is not exposed to web developers, this does not expose garbage collection timing.

3. Processing model

3.1. Potentially add LargestContentfulPaint entry

Note: A user agent implementing the Largest Contentful Paint API would need to include "largest-contentful-paint" in supportedEntryTypes for Window contexts. This allows developers to detect support for the API.

In order to potentially add a LargestContentfulPaint entry , the user agent must run the following steps:

3.2. Create a LargestContentfulPaint entry

In order to create a LargestContentfulPaint entry , the user agent must run the following steps:

3.3. Modifications to the DOM specification

This section will be removed once the [DOM] specification has been modified.

3.4. Modifications to the HTML specification

Each Window has has dispatched scroll event , a boolean which is initially set to false.

4. Security & privacy considerations

This API relies on Element Timing for its underlying primitives. LCP may expose some element not exposed by Element Timing in case that they are smaller than Element Timing’s limits, but are still the largest elements to be painted up until that point in the page’s loading. That does not seem to expose any sensitive information beyond what Element Timing already enables.