Using Navigation Timing

The Navigation Timing API lets you easily obtain detailed and highly accurate timing information to help isolate performance problems with your site's code or resources.

Unlike other tools or libraries, the Navigation Timing API lets you gather information that only the browser can provide at a level of accuracy much improved over other techniques. It also offers the advantage of being able to provide timing information as perceived by the user rather than data that has no correlation to what the user experiences.

Collecting timing information

Using the API is as simple as obtaining the Performance object using window.performance and looking up what you need within the object returned. For example, to measure the perceived loading time for a page:

window.addEventListener("load", function() {
  let now = new Date().getTime();
  let loadingTime = now - performance.timing.navigationStart;

  document.querySelector(".output").innerText =
        loadingTime + " ms";
}, false);

This code, executed when the load event occurs, subtracts from the current time the time at which the navigation whose timing was recorded began (performance.timing.navigationStart), and outputs that information to the screen by inserting it into an element.

In tandem with appropriate HTML and CSS, the result is:

The values listed are for the <iframe> in which the sample is presented above.

For a list of the available timing values you can look for in PerformanceTiming, see the PerformanceTiming interface's Properties section.

Determining navigation type

To put the timing information obtained from PerformanceTiming into the correct perspective, you need to know more about what sort of load operation occurred. In particular, you need to know:

  • Was this a load or a reload?
  • Was this a navigation or a move forward or backward through history?
  • How many (if any) redirects were required in order to complete the navigation?

This information is provided by the Performance.navigation property, which returns a PerformanceNavigation object that includes the needed information.

Let's add this information to the example above. The new code looks like this:

window.addEventListener("load", function() {
  let now = new Date().getTime();
  let loadingTime = now - performance.timing.navigationStart;

  output = "Load time: " + loadingTime + " ms<br/>";
  output += "Navigation type: ";

  switch(performance.navigation.type) {
      case PerformanceNavigation.TYPE_NAVIGATE:
        output += "Navigation";
      break;
    case PerformanceNavigation.TYPE_RELOAD:
        output += "Reload";
      break;
    case PerformanceNavigation.TYPE_BACK_FORWARD:
        output += "History";
      break;
    default:
        output += "Unknown";
      break;
  }

  output += "<br/>Redirects: " +
      performance.navigation.redirectCount;
  document.querySelector(".output").innerHTML = output;
}, false);

This amends the previous example by looking at the contents of the performance.navigation object. performance.navigation.type indicates what kind of load operation took place: a navigation, a reload, or a shift through the browser's history. We also obtain the number of redirects that were incurred during the navigation from performance.navigation.redirectCount. This information is output to the screen just like the page load time was previously: by inserting it into the element with class "output".

With this code in place, the result looks like this:

The values listed are for the <iframe> in which the sample is presented.

See also