Paint Timing 1

Editor’s Draft,

This version:
Latest published version:
Issue Tracking:
Inline In Spec
(Invited Expert)
Former Editor:


This document defines an API that can be used to capture a series of key moments (first paint, first contentful paint) during pageload which developers care about.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the Web Performance Working Group as an Editors Draft. This document is intended to become a W3C Recommendation.

Feedback and comments on this specification are welcome, please send them to public-web-perf@w3.org (subscribe, archives) with [paint-timing] at the start of your email’s subject.

Publication as an Editors Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2019 W3C Process Document.

1. Introduction

This section is non-normative.

Load is not a single moment in time — it’s an experience that no one metric can fully capture. There are multiple moments during the load experience that can affect whether a user perceives it as "fast" or "slow".

First paint (FP) is the first of these key moments, followed by first contentful paint (FCP). These metrics mark the points in time when the browser renders a given document. This is important to the user because it answers the question: is it happening?

The primary difference between the two metrics is FP marks the first time the browser renders anything for a given document. By contrast, FCP marks the time when the browser renders the first bit of image or text content from the DOM.

1.1. Usage example

var observer = new PerformanceObserver(function(list) {
    var perfEntries = list.getEntries();
    for (var i = 0; i < perfEntries.length; i++) {
        // 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:

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

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:

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:

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:

3. The PerformancePaintTiming interface

interface PerformancePaintTiming : PerformanceEntry {};

PerformancePaintTiming extends the following attributes of PerformanceEntry interface:

NOTE: A user agent implementing PerformancePaintTiming would need to include "paint" in supportedEntryTypes of a global object whose relevant settings object's responsible 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

To know whether Document document should report first contentful paint, perform the following steps:
  1. If document’s previously reported paints contains "first-contentful-paint", then return false.

  2. If document contains at least one element that is both paintable and contentful, then return true.

  3. Otherwise, return false.

4.1.2. Mark paint timing

When asked to mark paint timing given a Document document as input, perform the following steps:
  1. If the document's responsible browsing context is not paint-timing eligible, return.

  2. Let paintTimestamp be the current high resolution time.

  3. Let reportedPaints be the previously reported paints associated with document.

  4. If reportedPaints does not contain "first-paint", and the user agent is configured to mark first paint, then invoke the § 4.1.3 Report paint timing algorithm with document, "first-paint", and paintTimestamp.

    NOTE: First paint excludes the default background paint, but includes non-default background paint.

    This should be turned into a normative note.

  5. If document should report first contentful paint, then:

    1. Invoke the § 4.1.3 Report paint timing algorithm with document, "first-contentful-paint", and paintTimestamp as arguments.

    NOTE: A parent frame should not be aware of the paint events from its child iframes, and vice versa. This means that a frame that contains just iframes will have first paint (due to the enclosing boxes of the iframes) but no first contentful paint.

    NOTE: A document is not guaranteed to mark "first-paint" or "first-contentful-paint". A completely blank document may never mark first paint, and a document containing only elements that are not contentful, may never mark first contentful paint.

NOTE: The marking of first paint is optional. User-agents implementing paint timing should at the very least mark first contentful paint .

4.1.3. Report paint timing

When asked to report paint timing given document, paintType, and paintTimestamp as arguments, perform the following steps:
  1. Create a new PerformancePaintTiming object newEntry with document’s relevant realm and set its attributes as follows:

    1. Set newEntry’s name attribute to paintType.

    2. Set newEntry’s entryType attribute to "paint".

    3. Set newEntry’s startTime attribute to paintTimestamp.

    4. Set newEntry’s duration attribute to 0.

  2. Add the PerformanceEntry newEntry object.

  3. Append paintType to document’s associated previously reported paints.

5. Acknowledgements

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


Terms defined by this specification

Terms defined by reference


Normative References

Bert Bos; Elika Etemad; Brad Kemper. CSS Backgrounds and Borders Module Level 3. 17 October 2017. CR. URL: https://www.w3.org/TR/css-backgrounds-3/
Tantek Çelik; Chris Lilley; David Baron. CSS Color Module Level 3. 19 June 2018. REC. URL: https://www.w3.org/TR/css-color-3/
Tab Atkins Jr.; Elika Etemad. CSS Display Module Level 3. 11 July 2019. CR. URL: https://www.w3.org/TR/css-display-3/
Elika Etemad; Koji Ishii; Florian Rivoal. CSS Text Module Level 3. 13 November 2019. WD. URL: https://www.w3.org/TR/css-text-3/
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
Ilya Grigorik. High Resolution Time Level 2. 21 November 2019. REC. URL: https://www.w3.org/TR/hr-time-2/
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
Ilya Grigorik. Performance Timeline Level 2. 24 October 2019. WD. URL: https://www.w3.org/TR/performance-timeline-2/
Elika Etemad; Tab Atkins Jr.. Selectors Level 4. 21 November 2018. WD. URL: https://www.w3.org/TR/selectors-4/
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

IDL Index

interface PerformancePaintTiming : PerformanceEntry {};

Issues Index

This should be turned into a normative note.