PerformanceEventTiming

Description

This API enables visibility into slow events by providing event timestamps and duration for certain event types (see below). For example, you can monitor the time between a user action and the start of its event handler, or the time an event handler takes to run.

This API is particularly useful for measuring the Interaction to Next Paint (INP): the longest time (minus some outliers) from the point when a user interacts with your app to the point until the browser was actually able to respond to that interaction.

You typically work with PerformanceEventTiming objects by creating a PerformanceObserver instance and then calling its observe() method, passing in "event" or "first-input" as the value of the type option. The PerformanceObserver object's callback will then be called with a list of PerformanceEventTiming objects which you can analyze. See the example below for more.

By default, PerformanceEventTiming entries are exposed when their duration is 104ms or greater. Research suggests that user input that is not handled within 100ms is considered slow and 104ms is the first multiple of 8 greater than 100ms (for security reasons, this API is rounded to the nearest multiple of 8ms). However, you can set the PerformanceObserver to a different threshold using the durationThreshold option in the observe() method.

This interface inherits methods and properties from its parent, PerformanceEntry:

Events exposed

The following event types are exposed by the Event Timing API:

Note that the following events are not included in the list because they are continuous events and no meaningful event counts or performance metrics can be obtained at this point: mousemove, pointermove, pointerrawupdate, touchmove, wheel, drag.

To get a list of all exposed events, you can also look up keys in the performance.eventCounts map:

const exposedEventsList = [...performance.eventCounts.keys()];

Constructor

This interface has no constructor on its own. See the example below for how to typically get the information the PerformanceEventTiming interface holds.

Instance properties

This interface extends the following PerformanceEntry properties for event timing performance entry types by qualifying them as follows:

PerformanceEntry.duration Read only

Returns a DOMHighResTimeStamp representing the time from startTime to the next rendering paint (rounded to the nearest 8ms).

PerformanceEntry.entryType Read only

Returns "event" (for long events) or "first-input" (for the first user interaction).

PerformanceEntry.name Read only

Returns the associated event's type.

PerformanceEntry.startTime Read only

Returns a DOMHighResTimeStamp representing the associated event's timestamp property. This is the time the event was created and can be considered as a proxy for the time the user interaction occurred.

This interface also supports the following properties:

PerformanceEventTiming.cancelable Read only

Returns the associated event's cancelable property.

PerformanceEventTiming.interactionId Read only

Returns the ID that uniquely identifies the user interaction which triggered the associated event.

PerformanceEventTiming.processingStart Read only

Returns a DOMHighResTimeStamp representing the time at which event dispatch started. To measure the time between a user action and the time the event handler starts to run, calculate processingStart-startTime.

PerformanceEventTiming.processingEnd Read only

Returns a DOMHighResTimeStamp representing the time at which the event dispatch ended. To measure the time the event handler took to run, calculate processingEnd-processingStart.

PerformanceEventTiming.target Read only

Returns the associated event's last target, if it is not removed.

Instance methods

PerformanceEventTiming.toJSON()

Returns a JSON representation of the PerformanceEventTiming object.

Examples

Getting event timing information

To get event timing information, create a PerformanceObserver instance and then call its observe() method, passing in "event" or "first-input" as the value of the type option. You also need to set buffered to true to get access to events the user agent buffered while constructing the document. The PerformanceObserver object's callback will then be called with a list of PerformanceEventTiming objects which you can analyze.

const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    // Full duration
    const duration = entry.duration;

    // Input delay (before processing event)
    const delay = entry.processingStart - entry.startTime;

    // Synchronous event processing time
    // (between start and end dispatch)
    const eventHandlerTime = entry.processingEnd - entry.processingStart;
    console.log(`Total duration: ${duration}`);
    console.log(`Event delay: ${delay}`);
    console.log(`Event handler duration: ${eventHandlerTime}`);
  });
});

// Register the observer for events
observer.observe({ type: "event", buffered: true });

You can also set a different durationThreshold. The default is 104ms and the minimum possible duration threshold is 16ms.

observer.observe({ type: "event", durationThreshold: 16, buffered: true });

Specifications

Browser compatibility

See also

• Intersection Observer API
• Page Visibility API