PerformancePaintTiming

The PerformancePaintTiming interface provides timing information about "paint" (also called "render") operations during web page construction. "Paint" refers to conversion of the render tree to on-screen pixels.

There are two key paint moments this API provides:

  • First paint (FP): Time when anything is rendered. Note that the marking of the first paint is optional, not all user agents report it.
  • First contentful paint (FCP): Time when the first bit of DOM text or image content is rendered.

A third key paint moment is provided by the LargestContentfulPaint API:

  • Largest contentful paint (LCP): Render time of the largest image or text block visible within the viewport, recorded from when the page first begins to load.

The data this API provides helps you minimize the time that users have to wait before they can see the site's content start to appear. Decreasing the time until these key paint moments make sites feel more responsive, performant, and engaging for your users.

Like other Performance APIs, this API extends PerformanceEntry.

PerformanceEntry PerformancePaintTiming

Instance properties

This interface has no properties but it extends the following PerformanceEntry properties by qualifying and constraining the properties as follows:

PerformanceEntry.entryType

Returns "paint".

PerformanceEntry.name

Returns either "first-paint" or "first-contentful-paint".

PerformanceEntry.startTime

Returns the timestamp when the paint occurred.

PerformanceEntry.duration

Returns 0.

Instance methods

This interface has no methods.

Examples

Getting paint timings

Example using a PerformanceObserver, which notifies of new paint performance entries as they are recorded in the browser's performance timeline. Use the buffered option to access entries from before the observer creation.

js

const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    console.log(
      `The time to ${entry.name} was ${entry.startTime} milliseconds.`
    );
    // Logs "The time to first-paint was 386.7999999523163 milliseconds."
    // Logs "The time to first-contentful-paint was 400.6999999284744 milliseconds."
  });
});

observer.observe({ type: "paint", buffered: true });

Example using Performance.getEntriesByType(), which only shows paint performance entries present in the browser's performance timeline at the time you call this method:

js

const entries = performance.getEntriesByType("paint");
entries.forEach((entry) => {
  console.log(`The time to ${entry.name} was ${entry.startTime} milliseconds.`);
  // Logs "The time to first-paint was 386.7999999523163 milliseconds."
  // Logs "The time to first-contentful-paint was 400.6999999284744 milliseconds."
});

Specifications

Specification
Paint Timing
# sec-PerformancePaintTiming

Browser compatibility

BCD tables only load in the browser

See also