[go: up one dir, main page]

Largest Contentful Paint

Editor’s Draft,

More details about this document
This version:
https://w3c.github.io/largest-contentful-paint/
Latest published version:
https://www.w3.org/TR/largest-contentful-paint
Test Suite:
https://github.com/web-platform-tests/wpt/tree/master/largest-contentful-paint
Feedback:
GitHub
Editors:
(Google)
(Google)

Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

Abstract

This document defines an API that enables monitoring the largest paint an element triggered on screen.

Status of this document

This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

GitHub Issues are preferred for discussion of this specification.

This document is governed by the 03 November 2023 W3C Process Document.

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 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:

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.

1.1. 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.2. 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.3. Limitations

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

2. Terminology

A largest contentful paint candidate is a struct containing the following members:

An largest contentful paint candidate candidate is eligible to be largest contentful paint if it meets the following criteria:

3. Largest Contentful Paint

Largest Contentful Paint involves the following new interface:

3.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:

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 perform the following steps:

  1. If this's element is not exposed for paint timing given null, return null.

  2. Return this's element.

Note: The above algorithm defines that an element that is no longer a 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 (Element, Request) tuples. 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 tuples 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.

4. Processing model

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

4.1. Modifications to the DOM specification

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

We modify the event dispatch algorithm as follows.

Right after step 1, we add the following step:

4.2. Report Largest Contentful Paint

When asked to report largest contentful paint given a Document document, a timestamp now, an ordered set of pending image records paintedImages, and an ordered set of elements paintedTextNodes, perform the following steps:

  1. For each record of paintedImages:

    1. Let imageElement be record’s element.

    2. If imageElement is not exposed for paint timing, given document, continue.

    3. Let request be record’s request.

    4. Let candidate be (imageElement, request)

    5. Let intersectionRect be the value returned by the intersection rect algorithm using imageElement as the target and viewport as the root.

    6. Potentially add a LargestContentfulPaint entry with candidate, intersectionRect, now, record’s loadTime and document.

  2. For each textNode of paintedTextNodes,

    1. If textNode is not exposed for paint timing, given document, continue.

    2. Let candidate be (textNode, null)

    3. Let intersectionRect be an empty rectangle.

    4. For each Text node text of textNode’s set of owned text nodes:

      1. Augment intersectionRect to be smallest rectangle containing the border box of text and intersectionRect.

    5. Intersect intersectionRect with the visual viewport.

    6. Potentially add a LargestContentfulPaint entry with candidate, intersectionRect, now, 0, and document.

4.3. Determine the effective visual size of an element

In order to determine the effective visual size of an Element, run the following steps:

Input

intersectionRect, a DOMRectReadOnly

imageRequest, a Request

element, an Element

document, a Document

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 width.

  2. Let height be intersectionRect’s height.

  3. Let size be width * height.

  4. Let root be document’s browsing context’s top-level browsing context’s active document.

  5. Let rootWidth be root’s visual viewport’s width, excluding any scrollbars.

  6. Let rootHeight be root’s visual viewport’s height, excluding any scrollbars.

  7. If size is equal to rootWidth times rootHeight, return null.

  8. If imageRequest is not eligible to be largest contentful paint, return null.

  9. 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.

    2. 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.

    2. Let intersectingClientContentRect be the intersection of clientContentRect with intersectionRect.

    3. Set size to intersectingClientContentRect’s width * intersectingClientContentRect’s height.

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

    1. Let naturalArea be imageRequest’s natural width * imageRequest’s natural height.

    2. If naturalArea is 0, then return null.

    3. Let boundingClientArea be clientContentRect’s width * clientContentRect’s height.

    4. Let scaleFactor be boundingClientArea / naturalArea.

    5. If scaleFactor is greater than 1, then divide size by scaleFactor.

  10. Return size.

4.4. 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:

Input

candidate, a largest contentful paint candidate

intersectionRect, a DOMRectReadOnly

renderTime, a DOMHighResTimestamp

loadTime, a DOMHighResTimestamp

document, a Document

Output

None

  1. If document’s content set contains candidate, return.

  2. Append candidate to document’s content set

  3. Let window be document’s relevant global object.

  4. If either of window’s has dispatched scroll event or has dispatched input event is true, return.

  5. Let size be the effective visual size of candidate’s element given intersectionRect.

  6. If size is less than or equal to document’s largest contentful paint size, return.

  7. Let url be the empty string.

  8. If candidate’s request is not null, set url to be candidate’s request's request URL.

  9. Let id be candidate’s element's element id.

  10. Let contentInfo be a map with contentInfo["size"] = size, contentInfo["url"] = url, contentInfo["id"] = id, contentInfo["renderTime"] = renderTime, contentInfo["loadTime"] = loadTime, and contentInfo["element"] = candidate’s element.

  11. Create a LargestContentfulPaint entry with contentInfo, and document as inputs.

4.5. Create a LargestContentfulPaint entry

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

Input

contentInfo, a map

document, a Document

Output

None

  1. Set document’s largest contentful paint size to contentInfo["size"].

  2. Let entry be a new LargestContentfulPaint entry with document’s relevant realm, with its

    • size set to contentInfo["size"],

    • url set to contentInfo["url"],

    • id set to contentInfo["id"],

    • renderTime set to contentInfo["renderTime"],

    • loadTime set to contentInfo["loadTime"],

    • and element set to contentInfo["element"].

  3. Queue the PerformanceEntry entry.

5. Security & privacy considerations

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.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-BACKGROUNDS-3]
Elika Etemad; Brad Kemper. CSS Backgrounds and Borders Module Level 3. URL: https://drafts.csswg.org/css-backgrounds/
[CSS-BOX-4]
Elika Etemad. CSS Box Model Module Level 4. URL: https://drafts.csswg.org/css-box-4/
[CSS-IMAGES-3]
Tab Atkins Jr.; Elika Etemad; Lea Verou. CSS Images Module Level 3. URL: https://drafts.csswg.org/css-images-3/
[CSSOM-VIEW-1]
Simon Pieters. CSSOM View Module. URL: https://drafts.csswg.org/cssom-view/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[EVENT-TIMING]
Nicolas Pena Moreno; Tim Dresser. Event Timing API. URL: https://w3c.github.io/event-timing/
[FETCH]
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[GEOMETRY-1]
Simon Pieters; Chris Harrelson. Geometry Interfaces Module Level 1. URL: https://drafts.fxtf.org/geometry/
[HR-TIME-3]
Yoav Weiss. High Resolution Time. URL: https://w3c.github.io/hr-time/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[PAINT-TIMING]
Ian Clelland; Noam Rosenthal. Paint Timing. URL: https://w3c.github.io/paint-timing/
[PERFORMANCE-TIMELINE]
Nicolas Pena Moreno. Performance Timeline. URL: https://w3c.github.io/performance-timeline/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[STREAMS]
Adam Rice; et al. Streams Standard. Living Standard. URL: https://streams.spec.whatwg.org/
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/

Informative References

[ELEMENT-TIMING]
Element Timing API. cg-draft. URL: https://wicg.github.io/element-timing/

IDL Index

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