PerformanceSoftNavigation

The PerformanceSoftNavigation interface provides timing information about soft navigations as used by client-side routing on single-page application (SPA) sites. It is emitted when a browser observes a soft navigation to have taken place.

Instance properties

This interface directly defines the following properties:

PerformanceSoftNavigation.interactionId Read only: The id of the interaction that resulted in the soft navigation.
PerformanceSoftNavigation.navigationId Read only: The id of the navigation, unique to this page load.
PerformanceSoftNavigation.navigationType Read only: The type of the navigation.
PerformanceSoftNavigation.paintTime Read only: Returns the timestamp of when the first rendering phase ended and the paint phase started.
PerformanceSoftNavigation.presentationTime Read only: Returns the timestamp of when the first painted pixels were actually drawn on the screen.

It also extends the following PerformanceEntry properties, qualifying and constraining them as described:

PerformanceEntry.entryType Read only: Returns "soft-navigation".
PerformanceEntry.duration Read only: Returns the result of PerformanceSoftNavigation.presentationTime - PerformanceEntry.startTime.
PerformanceEntry.name Read only: The new URL navigated to.
PerformanceEntry.startTime Read only: Returns the timestamp of the interaction that resulted in the soft navigation.

Instance methods

This interface also inherits methods from PerformanceEntry.

PerformanceSoftNavigation.getLargestInteractionContentfulPaint(): Returns the current largest InteractionContentfulPaint for this soft navigation.

Description

The PerformanceSoftNavigation interface is driven by the browser observing the following:

A trusted user interaction.
A visible, contentful paint as a result of that interaction updating the screen.
A URL update in the user's address bar as a result of that interaction.

Having the browser provide this rather than a routing framework calling an API to emit this entry allows SPA performance timing to be measured consistently regardless of how different applications handle navigations (for example, updating the URL at the start or the end of navigation processing).

The PerformanceSoftNavigation interface allows developers to measure SPA performance metrics such as:

First Contentful Paint (FCP): Can be measured as the first paint from the soft navigation time.
Largest Contentful Paint (LCP): Can be measured via the InteractionContentfulPaint for the soft navigation.
Cumulative Layout Shift (CLS): Can be calculated between navigations.
Interaction to Next Paint (INP): Can be calculated between navigations.

Examples

undefined

Observing soft navigations

In the following example, a PerformanceObserver is used to log the soft navigations. The buffered flag is used to access data from before observer creation.

const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    console.log("Soft Nav:", entry.startTime, entry.name);
  }
});
observer.observe({ type: "soft-navigation", buffered: true });