Happy holiday folks! All the best from us at Digitpaint

Day 14

Measuring perceived performance with the Paint Timing API

We've looked into manual timing, navigation timing and the past two entries, but what if the problem is not in loading or not in your own code. What if the problem is in the rendering of the page? This is where the Paint Timing API comes in to play.

The Paint Timing API adds entries about paint to the performance entry buffer of your browser. Below we again show the page load but we show when the first paint and the first contentful paint happens.

Loading of this page

The paints won't show up in any browser except Chrome/Chrome for android and Opera at the moment.


If you're not familiar with painting, it's a simple concept to grasp, you take a brush and have at it … Except, when we're talking about painting in the browser we basically talk about the browser drawing pixels on screen. This are the moment where the user will see the element and styles you've concocted.

Knowing when the browser draws it's first pixels is quite an important metric. As it signifies the earliest possible moment at which something appears after a user has requested a page. A lot goes on as the browser is loading a page, but one thing we know is that the sooner we can get something to appear to the user, the sooner they'll realize that something is happening.

Measuring paints

The Paint Timing API allows you to get information on when the browser decides to draw something on screen. The API provides us with two metrics, the first-paint followed by the first-contentful-paint. These metrics answer two questions for the user about the page:

  • Is something being drawn on screen?
  • Is content being drawn on screen?

First Paint

This is the point in time (measured since the beginning of the page navigation) at which the first pixels are rendered on the screen. The first-paint measurement excludes the default background paint. It does, however, include any user defined backgrounds.

First Contentful Paint

This is the point at which the browser renders the first piece of DOM on the screen. This metric reports the time at which the browser first rendered any text, images, canvases, or SVGs.

Accessing the metrics

Accessing the metric happens throught the by now familiar buffer entries interface: performance.getEntriesByType("paint"). This should return two entries (one for first paint and one for first contentful paint. The returned objects are of the PerformanceEntry type and have the same interface as all other entries in the performance entry buffer. This means values we're looking for are in the startTime property.

Browser compatibility

While the performance framework is around in all major browsers, the paint timing entries are sadly not. Currently we're only looking at a working version in Blink based browsers. Apple and Microsoft are however positive about the API, so who knows?

  • chrome
  • android chrome
  • opera

Futher reading

Demo source code

Have a look to this demo, check out the source files:

Back to home