Paint Timing

1. Introduction

const observer = new PerformanceObserver(function(list) {
    const perfEntries = list.getEntries();
    for (const perfEntry of perfEntries) {
        // Process entries
        // report back for analytics and monitoring
        // ...
    }
});

// register observer for paint timing notifications
observer.observe({entryTypes: ["paint"]});

2. Terminology

Paint: the user agent has performed a "paint" (or "render") when it has converted the render tree to pixels on the screen. Formally, we consider the user agent to have "rendered" a document when it has performed the update the rendering steps of the event loop.

NOTE: The rendering pipeline is very complex, and the timestamp should be the latest timestamp the user agent is able to note in this pipeline (best effort). Typically the time at which the frame is submitted to the OS for display is recommended for this API.

A generated content pseudo-element is a paintable pseudo-element when all of the following apply:

• The pseudo-element’s used visibility is visible.

• The pseudo-element’s used opacity is greater than zero.

• The pseudo-element generates a non-empty box.

A CSS image img is a contentful image when all of the following apply:

• img is url valued.

• img is available.

A DOMString is non-empty if it contains at least one character excluding document white space characters.

An element target is contentful when one or more of the following apply:

• target has a text node child, representing non-empty text, and the node’s used opacity is greater than zero.

  NOTE: this covers the case where a typographical pseudo-element would override the opacity of the text node.

• target is a replaced element representing an available image.

• target has a background-image which is a contentful image, and its used background-size has non-zero width and height values.

• target is a canvas with its context mode set to any value other than none.

• target is a video element that represents its poster frame or the first video frame and the frame is available.

• target is an svg element with rendered descendants.

• target is an input element with a non-empty value attribute.

• target is an originating element for a paintable pseudo-element that represents a contentful image or non-empty text.

To compute the paintable bounding rect of element target, run the following steps:

1. Let boundingRect be the result of running the getBoundingClientRect on target.

2. Clip boundingRect with the document's scrolling area.

3. Return boundingRect.

NOTE: elements contained by boxes with overflow: scroll or overflow: hidden don’t have their paintable bounding rect clipped, as in both cases the element can become visible by scrolling.

An element el is paintable when all of the following apply:

• el is being rendered.

• el’s used visibility is visible.

• el and all of its ancestors' used opacity is greater than zero.

  NOTE: there could be cases where a paintable element would not be visible to the user, for example in the case of text that has the same color as its background. Those elements would still considered as paintable for the purpose of computing first contentful paint.

• el’s paintable bounding rect intersects with the scrolling area of the document.

  NOTE: This covers the cases where the element is scaled to zero size, has display: none, or display: contents where the contents resolve to an empty rect.

  NOTE: As a general rule, an element is paintable if it is within the viewport, or can potentially be in the viewport as a result of scrolling or zooming.

First paint entry contains a DOMHighResTimeStamp reporting the time when the user agent first rendered after navigation. This excludes the default background paint, but includes non-default background paint and the enclosing box of an iframe. This is the first key moment developers care about in page load – when the user agent has started to render the page.

A browsing context ctx is paint-timing eligible when one of the following apply:

• ctx is a top-level browsing context.

• ctx is a nested browsing context, and the user agent has configured ctx to report paint timing.

  NOTE: this allows user agents to enable paint-timing only for some of the frames, in addition to the main frame, if they so choose. For example, a user agent may decide to disable paint-timing for cross-origin iframes, as in some scenarios their paint-timing might reveal information about the main frame.

3. The PerformancePaintTiming interface

[Exposed=Window]
interface PerformancePaintTiming : PerformanceEntry {};

PerformancePaintTiming extends the following attributes of PerformanceEntry interface:

• The name attribute’s getter must return a DOMString for minimal frame attribution. Possible values of name are:

  • "first-paint": for first paint

  • "first-contentful-paint": for first contentful paint

• The entryType attribute’s getter must return "paint".

• The startTime attribute’s getter must return a DOMHighResTimeStamp of when the paint occured.

• The duration attribute’s getter must return 0.

NOTE: A user agent implementing PerformancePaintTiming would need to include "paint" in supportedEntryTypes of a global object whose browsing context is paint-timing eligible. This allows developers to detect support for paint timing for a particular browsing context.

4. Processing model

4.1. Reporting paint timing

Every Document has an associated set of previously reported paints, initiallized to an empty set.

4.1.1. First Contentful Paint

4.1.2. Mark paint timing

4.1.3. Report paint timing

5. Acknowledgements

Special thanks to all the contributors for their technical input and suggestions that led to improvements to this specification.