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 [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 February 2018 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 paint timing 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. The PerformancePaintTiming interface

interface PerformancePaintTiming : PerformanceEntry {};

PerformancePaintTiming extends the following attributes of PerformanceEntry interface:

A user agent implementing PerformancePaintTiming must perform the following steps:

  1. Run the register a performance entry type algorithm with "first-paint" as input.

  2. Run the register a performance entry type algorithm with "first-contentful-paint" as input.

4. Processing model

4.1. Reporting paint timing

4.1.1. Mark paint timing

Perform the following steps:
  1. Let paint-timestamp be the input timestamp.

  2. If this instance of update the rendering is the first paint, then record the timestamp as paint-timestamp and invoke the §4.1.2 Report paint timing algorithm with two arguments: "first-paint" and paint-timestamp.

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

  3. Otherwise, if this instance of update the rendering is the first contentful paint, then record the timestamp as paint-timestamp and invoke the §4.1.2 Report paint timing algorithm with two arguments: "first-contentful-paint" and paint-timestamp.

    NOTE: This paint must include text, image (including background images), non-white canvas or SVG.

  4. Otherwise, do nothing and return.

    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.

4.1.2. Report paint timing

Given two arguments paint-type and paint-timestamp, perform the following steps:
  1. Create a new PerformancePaintTiming object newEntry and set its attributes as follows:

    1. Set newEntry’s name attribute to paint-type

    2. Set newEntry’s entryType attribute to paint

    3. Set newEntry’s startTime attribute to paint-timestamp

    4. Set newEntry’s duration attribute to 0.

  2. Add the PerformanceEntry newEntry object.

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. 1 March 2018. CR. URL: https://www.w3.org/TR/hr-time-2/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[PERFORMANCE-TIMELINE-2]
Ilya Grigorik. Performance Timeline Level 2. 10 January 2019. WD. 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 {};