# Largest Contentful Paint

## Draft Community Group Report, 1 January 1970

This version:
  https://wicg.github.io/largest-contentful-paint
Test Suite:
  https://github.com/web-platform-tests/wpt/tree/master/largest-contentful-paint
Editors:
  Yoav Weiss (Google)
  Nicolás Peña Moreno (Google)

Copyright © 1970 the Contributors to the Largest Contentful Paint Specification, published by the Web Platform Incubator Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

## Abstract

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

## Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

## 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 correlated 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. Whenever content is removed, that content is no longer considered by the algorithm. In particular, if the content removed was the largest, then a new entry is created for the new largest. 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 splash screens, content cannot be considered as the largest once it is removed. This presents problems for websites with large image carousels where images rotate automatically. If the image is removed when the next one is painted and the carousel is the largest content, the algorithm will continuously update based on carousel updates.

## 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 value it was initialized to.

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

The `duration` attribute’s getter must return 0.

The `renderTime` attribute must return the value of the context object’s renderTime.

The `loadTime` attribute must return the value of the context object’s loadTime.

The `size` attribute must return the value of the context object’s size.

The `id` attribute must return the value of the context object’s id.

The `url` attribute must return the value of the context object’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, and a largest content, initially set to null. It also adds an associated content map, which is initially an empty map. The content map will be filled with entries with the following format:

- The key will be a pair with an `Element` as the first item and a `Request` as the second item. This allows identifying the content. The second item will be null for text content.

- The value will be a map which contains information that is required to fill up the `LargestContentfulPaint` entry. This allows exposing a new `LargestContentfulPaint` entry when content is removed from the page.

Note: A user agent probably wants to implement the `Document`'s associated concepts using a priority queue or binary search tree to avoid the O(n) cost of finding the largest size within content map when largest content is removed.

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

Input

  intersectionRect, a `DOMRectReadOnly`

  imageRequest, a `Request`

  renderTime, a DOMHighResTimestamp

  loadTime, a DOMHighResTimestamp

  element, an Element

  document, a Document

Output

  None

  1. Let contentIdentifier be the pair (element, imageRequest).

  2. If document’s content map contains contentIdentifier, return.

  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 url be the empty string.

  6. If imageRequest is not null, set url to be imageRequest’s request URL.

  7. Let id be element’s element id.

  8. Let width be intersectionRect’s `width`.

  9. Let height be intersectionRect’s `height`.

  10. Let size be `width * height`.

  11. If imageRequest is not null, run the following steps:

      1. Let naturalWidth and naturalHeight be the outputs of running the same steps for an `img`'s `naturalWidth` and `naturalHeight` attribute getters, but using imageRequest as the image.

      2. Let naturalSize be `naturalWidth * naturalHeight`.

      3. Let displayWidth and displayHeight be the outputs of running the same steps for an `img`'s `width` and `height` attribute getters, but using imageRequest as the image.

      4. Let displaySize be `displayWidth * displayHeight`.

      5. Let penaltyFactor be `min(displaySize, naturalSize) / displaySize`.

      6. Multiply size by penaltyFactor.

  12. Let contentInfo be a map with contentInfo["size"] = size, contentInfo["url"] = url, contentInfo["id"] = id, contentInfo["renderTime"] = renderTime, and contentInfo["loadTime"] = loadTime.

  13. Add a new entry with contentIdentifier as the key and contentInfo as the value to document’s content map.

  14. If size is smaller or equal to document’s largest contentful paint size, return.

  15. Create a LargestContentfulPaint entry with element and contentInfo as inputs.

### 3.2. Remove element content

In order to remove element content, the user agent must run the following steps:

Input

  element, an Element

  document, a Document

Output

  None

  1. For each entry of document’s content map:

     1. If entry’s key is a pair whose first item is equal to element, remove entry from document’s content map.

  2. If document’s largest content is a pair whose first item is not equal to element, then return.

  3. Let largestSize be 0, let largestContentIdentifier be null, and let largestContentInfo be null.

  4. For each key → value of document’s content map:

     1. If value["size"] is greater than largestSize, set largestSize to value["size"], largestContentIdentifier to key, and largestContentInfo to value.

  5. If largestContentIdentifier is not null, create a LargestContentfulPaint entry with largestContentIdentifier and largestContentInfo as inputs.

### 3.3. Create a LargestContentfulPaint entry

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

Input

  contentIdentifier, a pair

  contentInfo, a map

Output

  None

  1. Set document’s largest content to contentIdentifier.

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

  3. Let entry be a new `LargestContentfulPaint` entry, with it’s `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 its `element` set to contentIdentifier’s first item.

  4. Queue the PerformanceEntry entry.

### 3.4. 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:

- If target’s relevant global object is a `Window` object, event’s `type` is `scroll` and its `isTrusted` is false, set target’s relevant global object's has dispatched scroll event to true.

Add the following step at the end of the node removal algorithm:

- Call the algorithm to remove element content passing in node and node’s node document.

background image changes or changes in image `src` should trigger removal from the `Document`'s content map. <https://github.com/WICG/largest-contentful-paint/issues/41>

### 3.5. Modifications to the HTML specification

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

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.

## Conformance

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.

## Index

### Terms defined by this specification

- content map, in §2.1
- create a LargestContentfulPaint entry, in §3.3
- element
  - attribute for LargestContentfulPaint, in §2.1
  - definition of, in §2.1
- has dispatched scroll event, in §3.5
- id
  - attribute for LargestContentfulPaint, in §2.1
  - definition of, in §2.1
- largest content, in §2.1
- LargestContentfulPaint, in §2.1
- largest contentful paint size, in §2.1
- loadTime
  - attribute for LargestContentfulPaint, in §2.1
  - definition of, in §2.1
- potentially add a LargestContentfulPaint entry, in §3.1
- remove element content, in §3.2
- renderTime
  - attribute for LargestContentfulPaint, in §2.1
  - definition of, in §2.1
- size
  - attribute for LargestContentfulPaint, in §2.1
  - definition of, in §2.1
- toJSON(), in §2.1
- url
  - attribute for LargestContentfulPaint, in §2.1
  - definition of, in §2.1

https://drafts.csswg.org/cssom-view-1/#eventdef-document-scroll Referenced in:

- 3.4. Modifications to the DOM specification

https://dom.spec.whatwg.org/#document Referenced in:

- 2.1. LargestContentfulPaint interface (2) (3)
- 3.4. Modifications to the DOM specification

https://dom.spec.whatwg.org/#element Referenced in:

- 2.1. LargestContentfulPaint interface (2) (3)

https://dom.spec.whatwg.org/#context-object Referenced in:

- 2.1. LargestContentfulPaint interface (2) (3) (4) (5) (6) (7)

https://dom.spec.whatwg.org/#concept-tree-descendant Referenced in:

- 2.1. LargestContentfulPaint interface

https://dom.spec.whatwg.org#concept-document Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry
- 3.2. Remove element content

https://dom.spec.whatwg.org#dom-element-id Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry

https://dom.spec.whatwg.org#concept-event-dispatch Referenced in:

- 3.4. Modifications to the DOM specification

https://dom.spec.whatwg.org/#dom-event-istrusted Referenced in:

- 3.4. Modifications to the DOM specification

https://dom.spec.whatwg.org/#concept-node-document Referenced in:

- 3.4. Modifications to the DOM specification

https://dom.spec.whatwg.org#concept-node-remove Referenced in:

- 3.4. Modifications to the DOM specification

https://dom.spec.whatwg.org/#dom-event-type Referenced in:

- 3.4. Modifications to the DOM specification

https://wicg.github.io/element-timing/#sec-elements-exposed Referenced in:

- 1.1. Elements exposed

https://wicg.github.io/element-timing/#get-an-element Referenced in:

- 2.1. LargestContentfulPaint interface

https://wicg.github.io/event-timing#has-dispatched-input-event Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry

https://fetch.spec.whatwg.org/#request Referenced in:

- 2.1. LargestContentfulPaint interface
- 3.1. Potentially add LargestContentfulPaint entry

https://fetch.spec.whatwg.org/#dom-request-url Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry

https://drafts.fxtf.org/geometry-1/#domrectreadonly Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry

https://drafts.fxtf.org/geometry-1/#dom-domrectreadonly-height Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry

https://drafts.fxtf.org/geometry-1/#dom-domrectreadonly-width Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry

https://w3c.github.io/hr-time#dom-domhighrestimestamp Referenced in:

- 2.1. LargestContentfulPaint interface (2)

https://html.spec.whatwg.org/multipage/window-object.html#window Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry
- 3.4. Modifications to the DOM specification
- 3.5. Modifications to the HTML specification

https://html.spec.whatwg.org/multipage/webappapis.html#dom-img-height Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry

https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry (2)

https://html.spec.whatwg.org/multipage/webappapis.html#dom-img-naturalheight Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry

https://html.spec.whatwg.org/multipage/webappapis.html#dom-img-naturalwidth Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry

https://html.spec.whatwg.org/multipage/webappapis.html#concept-relevant-global Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry
- 3.4. Modifications to the DOM specification (2)

https://html.spec.whatwg.org/multipage/webappapis.html#dom-img-width Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry

https://infra.spec.whatwg.org/#map-exists Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry

https://infra.spec.whatwg.org/#ordered-map Referenced in:

- 2.1. LargestContentfulPaint interface
- 3.3. Create a LargestContentfulPaint entry

https://infra.spec.whatwg.org/#pair Referenced in:

- 2.1. LargestContentfulPaint interface
- 3.1. Potentially add LargestContentfulPaint entry
- 3.2. Remove element content (2)
- 3.3. Create a LargestContentfulPaint entry

https://infra.spec.whatwg.org/#map-remove Referenced in:

- 3.2. Remove element content

https://w3c.github.io/performance-timeline/#the-performanceentry-interface Referenced in:

- 2.1. LargestContentfulPaint interface

https://w3c.github.io/performance-timeline/#dom-performanceentry-duration Referenced in:

- 2.1. LargestContentfulPaint interface

https://w3c.github.io/performance-timeline/#dom-performanceentry-entrytype Referenced in:

- 2.1. LargestContentfulPaint interface

https://w3c.github.io/performance-timeline/#dom-performanceentry-name Referenced in:

- 2.1. LargestContentfulPaint interface

https://w3c.github.io/performance-timeline/#dfn-queue-a-performanceentry Referenced in:

- 3.3. Create a LargestContentfulPaint entry

https://w3c.github.io/performance-timeline/#dom-performanceentry-starttime Referenced in:

- 2.1. LargestContentfulPaint interface

https://w3c.github.io/performance-timeline/#supportedentrytypes-attribute Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry

https://heycam.github.io/webidl/#idl-DOMString Referenced in:

- 2.1. LargestContentfulPaint interface (2) (3)

https://heycam.github.io/webidl/#Default Referenced in:

- 2.1. LargestContentfulPaint interface

https://heycam.github.io/webidl/#Exposed Referenced in:

- 2.1. LargestContentfulPaint interface

https://heycam.github.io/webidl/#idl-object Referenced in:

- 2.1. LargestContentfulPaint interface

https://heycam.github.io/webidl/#idl-unsigned-long Referenced in:

- 2.1. LargestContentfulPaint interface

### Terms defined by reference

- [cssom-view-1] defines the following terms:
  - scroll
- [DOM] defines the following terms:
  - Document
  - Element
  - context object
  - descendant
  - document
  - element id
  - event dispatch algorithm
  - isTrusted
  - node document
  - node removal algorithm
  - type
- [element-timing] defines the following terms:
  - exposed
  - get an element
- [EVENT-TIMING] defines the following terms:
  - has dispatched input event
- [FETCH] defines the following terms:
  - Request
  - request url
- [geometry-1] defines the following terms:
  - DOMRectReadOnly
  - height
  - width
- [hr-time] defines the following terms:
  - DOMHighResTimeStamp
- [HTML] defines the following terms:
  - Window
  - height
  - img
  - naturalHeight
  - naturalWidth
  - relevant global object
  - width
- [INFRA] defines the following terms:
  - contain
  - map
  - pair
  - remove
- [performance-timeline-2] defines the following terms:
  - PerformanceEntry
  - duration
  - entryType
  - name
  - queue the performanceentry
  - startTime
  - supportedEntryTypes
- [WebIDL] defines the following terms:
  - DOMString
  - Default
  - Exposed
  - object
  - unsigned long

## References

### Normative References

[CSSOM-VIEW-1]
  Simon Pieters. CSSOM View Module. 17 March 2016. WD. URL: https://www.w3.org/TR/cssom-view-1/
[DOM]
  Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[EVENT-TIMING]
  Event Timing API. Living Standard. URL: https://wicg.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. 4 December 2018. CR. URL: https://www.w3.org/TR/geometry-1/
[HR-TIME]
  Jatinder Mann. High Resolution Time. 17 December 2012. REC. URL: https://www.w3.org/TR/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/
[PERFORMANCE-TIMELINE-2]
  Ilya Grigorik. Performance Timeline Level 2. 23 April 2019. WD. URL: https://www.w3.org/TR/performance-timeline-2/
[RFC2119]
  S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WebIDL]
  Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

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

## Issues Index

background image changes or changes in image `src` should trigger removal from the `Document`'s content map. <https://github.com/WICG/largest-contentful-paint/issues/41> ↵
#largestcontentfulpaint Referenced in:

- 2.1. LargestContentfulPaint interface (2) (3) (4)
- 3.1. Potentially add LargestContentfulPaint entry
- 3.3. Create a LargestContentfulPaint entry (2)

#dom-largestcontentfulpaint-rendertime Referenced in:

- 2.1. LargestContentfulPaint interface
- 3.3. Create a LargestContentfulPaint entry

#dom-largestcontentfulpaint-loadtime Referenced in:

- 2.1. LargestContentfulPaint interface
- 3.3. Create a LargestContentfulPaint entry

#dom-largestcontentfulpaint-size Referenced in:

- 2.1. LargestContentfulPaint interface
- 3.3. Create a LargestContentfulPaint entry

#dom-largestcontentfulpaint-id Referenced in:

- 2.1. LargestContentfulPaint interface
- 3.3. Create a LargestContentfulPaint entry

#dom-largestcontentfulpaint-url Referenced in:

- 2.1. LargestContentfulPaint interface
- 3.3. Create a LargestContentfulPaint entry

#dom-largestcontentfulpaint-element Referenced in:

- 2.1. LargestContentfulPaint interface (2)
- 3.3. Create a LargestContentfulPaint entry

#rendertime Referenced in:

- 2.1. LargestContentfulPaint interface (2)

#size Referenced in:

- 2.1. LargestContentfulPaint interface

#loadtime Referenced in:

- 2.1. LargestContentfulPaint interface (2)

#id Referenced in:

- 2.1. LargestContentfulPaint interface

#url Referenced in:

- 2.1. LargestContentfulPaint interface

#element Referenced in:

- 2.1. LargestContentfulPaint interface
- 3.1. Potentially add LargestContentfulPaint entry
- 3.2. Remove element content

#largest-contentful-paint-size Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry
- 3.3. Create a LargestContentfulPaint entry

#largest-content① Referenced in:

- 2.1. LargestContentfulPaint interface
- 3.2. Remove element content
- 3.3. Create a LargestContentfulPaint entry

#content-map Referenced in:

- 2.1. LargestContentfulPaint interface (2)
- 3.1. Potentially add LargestContentfulPaint entry (2)
- 3.2. Remove element content (2) (3)
- 3.4. Modifications to the DOM specification

#remove-element-content Referenced in:

- 3.4. Modifications to the DOM specification

#create-a-largestcontentfulpaint-entry Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry
- 3.2. Remove element content

#has-dispatched-scroll-event Referenced in:

- 3.1. Potentially add LargestContentfulPaint entry
- 3.4. Modifications to the DOM specification