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.
Syntax
Section titled “Syntax”const observer = new PerformanceObserver(callback)observer.observe({ type, buffered })observer.observe({ entryTypes })observer.disconnect()observer.takeRecords()PerformanceObserver.supportedEntryTypesperformance.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).
Parameters
Section titled “Parameters”| 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.
Exceptions
Section titled “Exceptions”| 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.
Support by engine
Section titled “Support by engine”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.
Examples
Section titled “Examples”Recording the start-up milestones
Section titled “Recording the start-up milestones”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.
Adjusting for a prerendered start
Section titled “Adjusting for a prerendered start”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.
See also
Section titled “See also”- Performance Timeline (w3.org)
- PerformanceObserver (developer.mozilla.org)
- PerformanceNavigationTiming (developer.mozilla.org)
- Core Web Vitals (LCP, INP, and CLS)
- Navigation preload and service worker boot time
- Back/forward cache (bfcache)
Specifications
| Specification | Status |
|---|---|
| None. | |