Skip to content

API in Performance

PerformanceObserver and paint timing

Published

PerformanceObserver receives entries as the browser adds them to the performance timeline, so you can measure PWA startup. The paint entries record the first pixels and first text or image; largest-contentful-paint records the render time of the largest image or text block visible in the viewport. A single navigation entry records milestones for the request, service worker, and document events. These are also the data that the web-vitals library reads through PerformanceObserver.

const observer = new PerformanceObserver(callback)
observer.observe({ type, buffered })
observer.observe({ entryTypes })
observer.disconnect()
observer.takeRecords()
PerformanceObserver.supportedEntryTypes
performance.getEntriesByType(type)

The callback receives a PerformanceObserverEntryList and the observer. observe() takes either one type with options or an entryTypes array without. PerformanceObserver is in Chrome 52, Firefox 57, and Safari 11; supportedEntryTypes in Chrome 73, Firefox 68, Safari 13 (BCD api.PerformanceObserver).

Parameter Type Meaning
callback function Called with the new entries, batched per task.
type string One entry type: "paint", "navigation", "largest-contentful-paint", "event", "layout-shift", "long-animation-frame", "resource", and others. Unknown types are ignored without error.
buffered boolean Deliver entries recorded before observe() was called, up to the engine’s per-type buffer. Required for paint and navigation entries, which are recorded before most scripts run. Only valid with type.
entryTypes array of strings Several types at once, without buffered.

The entries differ by type. A paint entry has name ("first-paint" or "first-contentful-paint"), startTime, and a duration of 0. A largest-contentful-paint entry adds element, size, url, and renderTime, and is emitted again each time a larger candidate paints until the first input. The one navigation entry carries the Navigation Timing milestones: workerStart (non-zero when a service worker handled the navigation), fetchStart, responseStart, domInteractive, loadEventEnd, type ("navigate", "reload", "back_forward", "prerender"), and activationStart, the time a prerendered document was shown, against which its other timestamps are adjusted.

Exception When
TypeError observe() is called with both type and entryTypes, or with neither, or buffered is passed with entryTypes.
TypeError The callback is not callable.
SyntaxError DOMException entryTypes is present but empty. (Some engines log a warning instead and observe nothing.)

Engine gaps are not exceptions: first-paint is reported by Chromium only (BCD api.PerformancePaintTiming.first-paint: Firefox and Safari false), layout-shift and long-animation-frame are Chromium only, and largest-contentful-paint arrived in Firefox 122 and Safari 26.2. An observer for an unsupported type does not fire.

PerformancePaintTiming is in Chrome 60, Firefox 84, and Safari 14.1, and PerformanceNavigationTiming in Chrome 57, Firefox 58, and Safari 15 (BCD), so both are usable everywhere a PWA runs, with the per-type gaps listed above. paintTime and presentationTime on paint entries, which separate the render from the display of the frame, are in Chrome 145 and Firefox 140 and absent in Safari. notRestoredReasons on the navigation entry is Chrome 125.

One observer per type, each with buffered: true, collects everything the browser recorded before the script ran. The LCP handler keeps the latest candidate and reports once the user interacts.

const report = {};
new PerformanceObserver((list) => {
for (const entry of list.getEntries()) report[entry.name] = entry.startTime;
}).observe({ type: 'paint', buffered: true });
new PerformanceObserver((list) => {
const last = list.getEntries().at(-1);
if (last) report.lcp = last.startTime;
}).observe({ type: 'largest-contentful-paint', buffered: true });
new PerformanceObserver((list) => {
const [nav] = list.getEntries();
report.ttfb = nav.responseStart;
report.workerBoot = nav.workerStart > 0 ? nav.fetchStart - nav.workerStart : 0;
}).observe({ type: 'navigation', buffered: true });
addEventListener('visibilitychange', () => {
if (document.visibilityState === 'hidden') navigator.sendBeacon('/metrics', JSON.stringify(report));
}, { once: true });

Sending on visibilitychange rather than unload adds no unload listener, and per web.dev Firefox on desktop makes pages with an unload listener ineligible for the back/forward cache.

A prerendered page’s timestamps start when prerendering began, not when the user saw it. Subtract activationStart so a prerendered visit is comparable with a normal one.

function visibleStart(entry) {
const [nav] = performance.getEntriesByType('navigation');
const activation = nav?.activationStart ?? 0;
return Math.max(entry.startTime - activation, 0);
}

A first-contentful-paint that happened during prerendering comes out as 0 with this helper, because Math.max clamps the negative difference. Treat 0 as “already painted at activation”, not as a measured paint time.

Detecting the observer and reading the buffer directly

Section titled “Detecting the observer and reading the buffer directly”

performance.getEntriesByType() returns what is already on the timeline, which is enough for paint and navigation entries in an engine without PerformanceObserver.

function paintTimings() {
if ('PerformanceObserver' in window
&& PerformanceObserver.supportedEntryTypes.includes('paint')) {
return new Promise((resolve) => {
new PerformanceObserver((list) => resolve(list.getEntries())).observe({ type: 'paint', buffered: true });
});
}
if (!('performance' in window) || typeof performance.getEntriesByType !== 'function') {
return Promise.resolve([]); // no timeline at all: report nothing
}
return Promise.resolve(performance.getEntriesByType('paint'));
}

The direct read misses a paint that happens after the call, which for the two paint entries is only a concern for scripts that run before the first paint.

Specifications

SpecificationStatus
None.