W3C

Paint Timing 1

Editor’s Draft,

This version:
https://w3c.github.io/paint-timing/
Latest published version:
https://www.w3.org/TR/paint-timing/
Issue Tracking:
GitHub
Editor:
(Google)

Abstract

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 %5Bpaint-timing%5D 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 5 February 2004 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 2017 W3C Process Document.

1. Introduction

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, immediately after navigation, when the browser renders pixels to the screen. 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 point when the browser renders anything that is visually different from what was on the screen prior to navigation. By contrast, FCP is the point when the browser renders the first bit of content from the DOM, which may be text, an image, SVG, or even a canvas element.

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 long task notifications
observer.observe({entryTypes: ["paint"]});

2. Terminology

Paint: the browser has performed a "paint" (or "render") when it has converted the render tree to pixels on the screen. This is formally defined as the when "update the rendering" happens in event loop processing.

NOTE: The rendering pipeline is very complex, and the timestamp should be the latest timestamp the browser 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.

First Paint entry contains a DOMHighResTimeStamp reporting the time when the browser 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 browser has started to render the page.

First Contentful Paint entry contains a DOMHighResTimeStamp reporting the time when the browser first rendered any text, image (including background images), non-white canvas or SVG. This excludes any content of iframes, but includes text with pending webfonts. This is the first time users could start consuming page content.

3. Paint Timing

Paint timing involves the following new interface

3.1. PerformancePaintTiming interface

interface PerformancePaintTiming : PerformanceEntry {};

PerformancePaintTiming extends the following attributes of PerformanceEntry interface:

4. Processing model

4.1. Modifications to other specifications

4.1.1. HTML: event loop processing model

During step 7.12 in "update the rendering":

4.2. Reporting Paint Timing

4.2.1. Mark Paint Timing

Perform the following steps:

4.2.2. Report Paint Timing

Given two arguments paint-type and paint-timestamp, perform the following steps:

5. Acknowledgements

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

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[HR-TIME-2]
Ilya Grigorik; James Simonsen; Jatinder Mann. High Resolution Time Level 2. 3 August 2017. CR. URL: https://www.w3.org/TR/hr-time-2/
[PERFORMANCE-TIMELINE-2]
Ilya Grigorik; Jatinder Mann; Zhiheng Wang. Performance Timeline Level 2. 8 December 2016. CR. URL: https://www.w3.org/TR/performance-timeline-2/
[WebIDL]
Cameron McCormack; Boris Zbarsky; Tobie Langel. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

IDL Index

interface PerformancePaintTiming : PerformanceEntry {};