Paint Timing

W3C Working Draft,

More details about this document
This version:
Latest published version:
Editor's Draft:
Previous Versions:
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. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at

This document was published by the Web Performance Working Group as a Working Draft using the Recommendation track. Publication as a Working Draft does not imply endorsement by W3C and its Members.

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.

GitHub Issues are preferred for discussion of this specification.

This document is governed by the 2 November 2021 W3C Process Document.

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.

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

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:

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


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.


Terms defined by this specification

Terms defined by reference


Normative References

Bert Bos; Elika Etemad; Brad Kemper. CSS Backgrounds and Borders Module Level 3. 14 February 2023. CR. URL:
Tantek Çelik; Chris Lilley; David Baron. CSS Color Module Level 3. 18 January 2022. REC. URL:
Elika Etemad; Tab Atkins Jr.. CSS Display Module Level 3. 30 March 2023. CR. URL:
Elika Etemad; et al. CSS Text Module Level 4. 29 March 2023. WD. URL:
Anne van Kesteren. DOM Standard. Living Standard. URL:
Ilya Grigorik. High Resolution Time Level 2. 21 November 2019. REC. URL:
Yoav Weiss. High Resolution Time. 25 April 2023. WD. URL:
Anne van Kesteren; et al. HTML Standard. Living Standard. URL:
Nicolas Pena Moreno. Performance Timeline. 15 November 2022. CR. URL:
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL:
Elika Etemad; Tab Atkins Jr.. Selectors Level 4. 11 November 2022. WD. URL:
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL:

IDL Index

interface PerformancePaintTiming : PerformanceEntry {};

Issues Index

This should be turned into a normative note.


In all current engines.

Edge (Legacy)?IENone
Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?