Frame Timing API

The PerformanceFrameTiming interface provides frame timing data about the browser's event loop. A frame represents the amount of work a browser does in one event loop iteration such as processing DOM events, resizing, scrolling, rendering, CSS animations, etc. A frame rate of 60 fps (frames per second) for a 60 Hz refresh rate is a common target for a good responsive user experience. This means the browser should process a frame in about 16.7 ms.

An application can register a PerformanceObserver for "frame" performance entry types. The observer (callback) will be notified when new "frame" events are added to the browser's performance timeline and the frame's duration (length of time) will be available. This data can be used to help identify areas that take too long to provide a good user experience.

Example code of the interfaces described in this document is included in Using the Frame Timing API.

Performance frames

The PerformanceFrameTiming interface extends the following PerformanceEntry properties (for "frame" performance entry types) by qualifying and constrainting the properties as follows:

PerformanceEntry.entryType

Set to "frame".

PerformanceEntry.name

Set to the document's address.

PerformanceEntry.startTime

Set to the DOMHighResTimeStamp when the frame was started.

PerformanceEntry.duration

Set to a timestamp indicating the difference between the startTimes of two successive frames.

This data, particularly the duration timestamp, can be used to help identify performance problems.

Frame observers

The performance observer interfaces allow an application to register an observer for specific performance event types. When one of those event types is recorded in the browser's performance timeline, the application is notified of the event via the observer's callback function that was specified when the observer was created.

To observe "frame" performance entry types, the application first creates a PerformanceObserver object with a specific frame observer callback (function). Next, PerformanceObserver.observe() is used to specify the set of performance events to observe - in this case, just the "frame" event type. When the browser adds a new frame to the performance timeline, the specified observer callback will be invoked.

Accessing frame data

When a frame observer is invoked, frame performance entries can be retrieved by calling PerformanceObserverEntryList.getEntriesByType() with an argument of "frame". This method returns a list of "frame" PerformanceEntry objects. Each frame object's duration property returns the timestamp of two consecutive frames. If this value is greater than the time needed to provide a good user experience, further analysis might be warranted.

Browser compatibility

As shown in the PerformanceFrameTiming interface's Browser Compatibility table, this interface has no implementations.

See also

• Frame Rate (Firefox Performance Tool)
• Using the Frame Timing API