index.bs

<pre class=metadata>
Title: Largest Contentful Paint
Status: ED
Shortname: largest-contentful-paint
Group: webperf
Level: none
Editor: Yoav Weiss, Google https://google.com, yoavweiss@chromium.org, w3cid 58673
Editor: Nicolás Peña Moreno, Google https://google.com, npm@chromium.org, w3cid 103755
TR: https://www.w3.org/TR/largest-contentful-paint
URL: https://w3c.github.io/largest-contentful-paint/
Repository: https://github.com/w3c/largest-contentful-paint/
Test Suite: https://github.com/web-platform-tests/wpt/tree/master/largest-contentful-paint
Abstract: This document defines an API that enables monitoring the largest paint an element triggered on screen.
Default Highlight: js
Include Mdn Panels: no
</pre>

<pre class=anchors>
urlPrefix: https://w3c.github.io/performance-timeline/; spec: PERFORMANCE-TIMELINE-2;
    type: interface; url: #the-performanceentry-interface; text: PerformanceEntry;
    type: attribute; for: PerformanceEntry;
        text: name; url: #dom-performanceentry-name;
        text: entryType; url: #dom-performanceentry-entrytype;
        text: startTime; url: #dom-performanceentry-starttime;
        text: duration; url: #dom-performanceentry-duration;
    type: dfn; url: #dfn-queue-a-performanceentry; text: queue the PerformanceEntry;
    type: attribute; for: PerformanceObserver;
        text: supportedEntryTypes; url: #supportedentrytypes-attribute;
urlPrefix: https://wicg.github.io/element-timing/; spec: ELEMENT-TIMING;
    type: dfn; url: #sec-elements-exposed; text: exposed;
    type: dfn; url: #get-an-element; text: get an element;
urlPrefix: https://w3c.github.io/hr-time; spec: HR-TIME;
    type: dfn; url: #dfn-current-high-resolution-time; text: current high resolution time;
    type: interface; url: #dom-domhighrestimestamp; text: DOMHighResTimeStamp;
urlPrefix: https://dom.spec.whatwg.org; spec: DOM;
    type: dfn; url: #concept-document; text: Document;
    type: dfn; url: #concept-element; text: Element;
    type: attribute; for: Element;
        text: element id; url: #dom-element-id;
    type: dfn; url: #concept-event-dispatch; text: event dispatch algorithm;
urlPrefix: https://wicg.github.io/event-timing; spec: EVENT-TIMING;
    type: dfn; url: #has-dispatched-input-event; text: has dispatched input event;
urlPrefix: https://fetch.spec.whatwg.org/; spec: FETCH;
    type: dfn; url: #dom-request-url; text: request URL
urlPrefix: https://html.spec.whatwg.org/multipage/webappapis.html; spec: html;
    type: dfn; text: relevant global object; url: concept-relevant-global;
    type: attribute; for: img;
        text: naturalWidth; url: #dom-img-naturalwidth;
        text: naturalHeight; url: #dom-img-naturalheight;
        text: width; url: #dom-img-width;
        text: height; url: #dom-img-height;
urlPrefix: https://drafts.csswg.org/cssom-view/; spec: CSSOM-VIEW;
    type: dfn; text: visual viewport; url: visual-viewport;
urlPrefix: https://drafts.csswg.org/css-color-3/; spec: CSS-COLOR-3;
    type: dfn; text: transparent;
urlPrefix: https://w3c.github.io/paint-timing/; spec: PAINT-TIMING;
    type: dfn; url:#the-paint-timing-steps; text: the paint timing steps
    type: dfn; url:#set-of-owned-text-nodes; text: set of owned text nodes
    type: dfn; url:#exposed-for-paint-timing; text: exposed for paint timing
    type: dfn; url:#pending-image-record; text: pending image record
    type: dfn; for:pending image record; url:#pending-image-record-element; text: element
    type: dfn; for:pending image record; url:#pending-image-record-loadtime; text: loadTime
    type: dfn; for:pending image record; url:#pending-image-record-request; text: request
    type: dfn; url:#timing-eligible; text: timing-eligible
    type: dfn; text: paint timing info;
    type: dfn; for: PaintTimingMixin; text: paint timing info;
    type: dfn; for: paint timing info; text: default paint timestamp;
    type: interface; text: PaintTimingMixin;
</pre>

Introduction {#sec-intro}
=====================

<em>This section is non-normative.</em>
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 need a reliable metric that correlates with their user's visual rendering experience. Paint loading 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 page-load metric that:
* better correlates with user experience than First Paint and First Contentful Paint
* 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 concepts defined in [[PAINT-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.


NOTE: The Largest Contentful Paint API will only expose elements that are [=timing-eligible=]. Note that unlike Element Timing, there is no need to annotate elements in order to have them be eligible for Largest Contentful Paint.

Largest content {#sec-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.

Usage example {#sec-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.

<xmp class="example highlight" highlight=html>
    <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>
</xmp>

Limitations {#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.

Terminology {#sec-terminology}
==============================

A <dfn>largest contentful paint candidate</dfn> is a [=struct=] containing the
following members:

* <dfn for="largest contentful paint candidate">element</dfn>, an [=/element=]
* <dfn for="largest contentful paint candidate">request</dfn>, a [=/Request=] or null

An [=largest contentful paint candidate=] |candidate| is <dfn>eligible to be largest contentful paint</dfn> if it meets the
following criteria:

* |candidate|'s [=largest contentful paint candidate/element=]'s opacity is > 0
* |candidate|'s [=largest contentful paint candidate/element=] is a text node, or |candidate|'s [=largest contentful paint candidate/request=]'s
    [=/response=]'s content length in bytes is >= |candidate|'s [=largest contentful paint candidate/element=]'s [=effective visual size=] * 0.004

    Note: This heuristic tests whether the image resource contains sufficient data to be seen as contentful to the user. It compares the transferred file size with the number of pixels which are actually produced, after decoding and any image scaling is applied. Images which encode a very large number of pixels with in a very small number of bytes are typically low-content backgrounds, gradients, and the like, and are not considered as [=largest contentful paint candidates=].

Largest Contentful Paint {#sec-largest-contentful-paint}
=======================================

Largest Contentful Paint involves the following new interface:

{{LargestContentfulPaint}} interface {#sec-largest-contentful-paint-interface}
------------------------------------------------------------------------

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

LargestContentfulPaint includes PaintTimingMixin;
</pre>

Each {{LargestContentfulPaint}} object has these associated concepts:
* A <dfn for="LargestContentfulPaint">size</dfn>, initially set to 0.
* A <dfn for="LargestContentfulPaint">loadTime</dfn>, initially set to 0.
* An <dfn for="LargestContentfulPaint">id</dfn>, initially set to the empty string.
* A <dfn for="LargestContentfulPaint">url</dfn>, initially set to the empty string.
* An <dfn for="LargestContentfulPaint">element</dfn> containing the associated {{Element}}, initially set to <code>null</code>.

The {{PerformanceEntry/entryType}} attribute's getter must return the {{DOMString}} <code>"largest-contentful-paint"</code>.

The {{PerformanceEntry/name}} attribute's getter must return the empty string.

The {{PerformanceEntry/startTime}} attribute's getter must return the value of [=this=]'s {{LargestContentfulPaint/renderTime}} if it is not 0, and the value of [=this=]'s [=LargestContentfulPaint/loadTime=] otherwise.

The {{PerformanceEntry/duration}} attribute's getter must return 0.

The {{LargestContentfulPaint/renderTime}} attribute must return the [=default paint timestamp=] given [=this=]'s [=PaintTimingMixin/paint timing info=].

The {{LargestContentfulPaint/loadTime}} attribute must return the value of [=this=]'s [=LargestContentfulPaint/loadTime=].

The {{LargestContentfulPaint/size}} attribute must return the value of [=this=]'s [=LargestContentfulPaint/size=].

The {{LargestContentfulPaint/id}} attribute must return the value of [=this=]'s [=LargestContentfulPaint/id=].

The {{LargestContentfulPaint/url}} attribute must return the value of [=this=]'s [=LargestContentfulPaint/url=].

The {{LargestContentfulPaint/element}} attribute's getter must perform the following steps:
<div algorithm="LargestContentfulPaint element">
    1. If [=this=]'s [=LargestContentfulPaint/element=] is not [=exposed for paint timing=] given null, return null.
    1. Return [=this=]'s [=LargestContentfulPaint/element=].
</div>

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

This specification also extends {{Document}} by adding to it a <dfn>largest contentful paint size</dfn> concept, initially set to 0.
It also adds an associated <dfn>content set</dfn>, which is initially an empty <a spec=infra for=/>set</a>. The [=content set=] will be filled with ({{Element}}, {{Request}}) <a>tuples</a>. 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 <a>tuples</a> to weak pointers to the {{Element|Elements}} so that it can be cleaned up sometime after the {{Element|Elements}} are removed. Since the <a spec=infra for=/>set</a> is not exposed to web developers, this does not expose garbage collection timing.

Processing model {#sec-processing-model}
========================================

Each {{Window}} has <dfn>has dispatched scroll event</dfn>, a boolean which is initially set to false.


Modifications to the DOM specification {#sec-modifications-DOM}
---------------------------------------------------------------

<em>This section will be removed once the [[DOM]] specification has been modified.</em>

<div algorithm="additions to event dispatch">
    We modify the <a>event dispatch algorithm</a> as follows.

    Right after step 1, we add the following step:

    * If |target|'s [=relevant global object=] is a {{Window}} object, <var ignore>event</var>'s {{Event/type}} is {{Document/scroll}} and its {{Event/isTrusted}} is true, set |target|'s [=relevant global object=]'s [=has dispatched scroll event=] to true.
</div>

Report Largest Contentful Paint {#sec-report-largest-contentful-paint}
----------------------------------------------------------------------

<div export algorithm="report largest contentful paint">
    When asked to <dfn>report largest contentful paint</dfn> given a {{Document}} |document|, a [=/paint timing info=] |paintTimingInfo|, an [=ordered set=] of [=pending image records=] |paintedImages|, and an [=ordered set=] of [=/elements=] |paintedTextNodes|, perform the following steps:

    1. [=list/For each=] |record| of |paintedImages|:
        1. Let |imageElement| be |record|'s [=pending image record/element=].
        1. If |imageElement| is not [=exposed for paint timing=], given |document|, continue.
        1. Let |request| be |record|'s [=pending image record/request=].
        1. Let |candidate| be (|imageElement|, |request|)
        1. Let |intersectionRect| be the value returned by the intersection rect algorithm using |imageElement| as the target and viewport as the root.
        1. <a>Potentially add a LargestContentfulPaint entry</a> with |candidate|, |intersectionRect|, |paintTimingInfo|, |record|'s [=pending image record/loadTime=] and |document|.
    1. [=list/For each=] |textNode| of |paintedTextNodes|,
        1. If |textNode| is not [=exposed for paint timing=], given |document|, continue.
        1. If |textNode| has [=alpha channel=] value <=0 or [=opacity=] value <=0:
            1. If |textNode|'s <a property>text-shadow</a> value is none, |textNode|'s 'stroke-color' value is [=transparent=] and |textNode|'s 'stroke-image' value is none, continue.
        1. Let |candidate| be (|textNode|, null)
        1. Let |intersectionRect| be an empty rectangle.
        1. [=set/For each=] {{Text}} <a>node</a> |text| of |textNode|'s <a>set of owned text nodes</a>:
            1. Augment |intersectionRect| to be smallest rectangle containing the border box of |text| and |intersectionRect|.
        1. Intersect |intersectionRect| with the visual viewport.
        1. <a>Potentially add a LargestContentfulPaint entry</a> with |candidate|, |intersectionRect|, |paintTimingInfo|, 0, and |document|.
</div>

Determine the effective visual size of an element {#sec-effective-visual-size}
------------------------------------------------------------------------------

In order to determine the <dfn export>effective visual size</dfn> of an [=/Element=],
run the following steps:

<div algorithm="LargestContentfulPaint effective-visual-size">
    : Input
    ::  |intersectionRect|, a {{DOMRectReadOnly}}
    ::  |imageRequest|, a {{Request}}
    ::  |element|, an [=/Element=]
    ::  |document|, a <a>Document</a>
    : Output
    ::  The size to report for Largest Contentful Paint, in pixels, or null if the element should not be an LCP candidate.
        1. Let |width| be |intersectionRect|'s {{DOMRectReadOnly/width}}.
        1. Let |height| be |intersectionRect|'s {{DOMRectReadOnly/height}}.
        1. Let |size| be <code>|width| * |height|</code>.
        1. Let |root| be |document|'s <a for="Document">browsing context</a>'s <a>top-level browsing context</a>'s <a>active document</a>.
        1. Let |rootWidth| be |root|'s <a>visual viewport</a>'s width, excluding any scrollbars.
        1. Let |rootHeight| be |root|'s <a>visual viewport</a>'s height, excluding any scrollbars.
        1. If |size| is equal to |rootWidth| times |rootHeight|, return null.
        1. If |imageRequest| is not [=eligible to be largest contentful paint=], return null.
        1. If |imageRequest| is not null, run the following steps to adjust for image position and upscaling:
            1. Let |concreteDimensions| be |imageRequest|'s [=concrete object size=] within |element|.
            1. Let |visibleDimensions| be |concreteDimensions|, adjusted for positioning by 'object-position' or 'background-position' and |element|'s [=content box=].

               Note: some of those algorithms are not rigorously defined in CSS. The expected result is to get the actual position and size of the image in |element| as a {{DOMRectReadOnly}}.

            1. Let |clientContentRect| be the smallest {{DOMRectReadOnly}} containing |visibleDimensions| with |element|'s [=transforms=] applied.
            1. Let |intersectingClientContentRect| be the intersection of |clientContentRect| with |intersectionRect|.
            1. Set |size| to <code>|intersectingClientContentRect|'s {{DOMRectReadOnly/width}} * |intersectingClientContentRect|'s {{DOMRectReadOnly/height}}</code>.

               Note: this ensures that we only intersect with the image itself and not with the element's decorations.

            1. Let |naturalArea| be <code>|imageRequest|'s [=natural width=] * |imageRequest|'s [=natural height=]</code>.
            1. If |naturalArea| is 0, then return null.
            1. Let |boundingClientArea| be <code>|clientContentRect|'s {{DOMRectReadOnly/width}} * |clientContentRect|'s {{DOMRectReadOnly/height}}</code>.
            1. Let |scaleFactor| be <code>|boundingClientArea| / |naturalArea|</code>.
            1. If |scaleFactor| is greater than 1, then divide |size| by |scaleFactor|.

        1. Return |size|.
</div>

Potentially add LargestContentfulPaint entry {#sec-add-lcp-entry}
-----------------------------------------------------------------

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

In order to <dfn export>potentially add a {{LargestContentfulPaint}} entry</dfn>, the user agent must run the following steps:
<div algorithm="LargestContentfulPaint potentially-add-entry">
    : Input
    ::  |candidate|, a [=largest contentful paint candidate=]
    ::  |intersectionRect|, a {{DOMRectReadOnly}}
    ::  |paintTimingInfo|, a [=/paint timing info=]
    ::  |loadTime|, a DOMHighResTimestamp
    ::  |document|, a <a>Document</a>
    : Output
    ::  None
        1. If |document|'s [=content set=] <a for=set>contains</a> |candidate|, return.
        1. <a for=set>Append</a> |candidate| to |document|'s [=content set=]
        1. Let |window| be |document|’s [=relevant global object=].
        1. If either of |window|'s [=has dispatched scroll event=] or [=has dispatched input event=] is true, return.
        1. Let |size| be the [=effective visual size=] of |candidate|'s [=/element=] given |intersectionRect|.
        1. If |size| is less than or equal to |document|'s [=largest contentful paint size=], return.
        1. Let |url| be the empty string.
        1. If |candidate|'s [=largest contentful paint candidate/request=] is not null, set |url| to be |candidate|'s [=largest contentful paint candidate/request=]'s [=request URL=].
        1. Let |id| be |candidate|'s [=largest contentful paint candidate/element=]'s <a attribute for=Element>element id</a>.
        1. Let |contentInfo| be a <a>map</a> with |contentInfo|["size"] = |size|, |contentInfo|["url"] = |url|, |contentInfo|["id"] = |id|, |contentInfo|["loadTime"] = |loadTime|, and contentInfo["element"] = |candidate|'s [=largest contentful paint candidate/element=].
        1. <a>Create a LargestContentfulPaint entry</a> with |contentInfo|, |paintTimingInfo|, and |document| as inputs.
</div>

Create a LargestContentfulPaint entry {#sec-create-entry}
--------------------------------------------------------

In order to <dfn>create a {{LargestContentfulPaint}} entry</dfn>, the user agent must run the following steps:

<div algorithm="LargestContentfulPaint create-entry">
    : Input
    ::  |contentInfo|, a <a>map</a>
    ::  |paintTimingInfo|, a [=/paint timing info=]
    ::  |document|, a {{Document}}
    : Output
    ::  None
        1. Set |document|'s [=largest contentful paint size=] to |contentInfo|["size"].
        1. Let |entry| be a new {{LargestContentfulPaint}} entry with |document|'s [=relevant realm=], whose [=PaintTimingMixin/paint timing info=] is |paintTimingInfo|, with its
            * {{LargestContentfulPaint/size}} set to |contentInfo|["size"],
            * {{LargestContentfulPaint/url}} set to |contentInfo|["url"],
            * {{LargestContentfulPaint/id}} set to |contentInfo|["id"],
            * {{LargestContentfulPaint/loadTime}} set to |contentInfo|["loadTime"],
            * and {{LargestContentfulPaint/element}} set to |contentInfo|["element"].
        1. [=Queue the PerformanceEntry=] |entry|.
</div>

Security & privacy considerations {#sec-security}
=================================================

This API relies on Paint Timing for its underlying primitives. Unlike the similar API Element Timing, LCP may expose timing details of some elements with small sizes, if they 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.