JavaScript Network Information API Connection Speed

The Network Information API provides web developers with programmatic access to information about a user’s active network connection directly through JavaScript. By reading properties exposed on the navigator.connection object, web applications can determine connection speed, latency, and general network quality, allowing them to dynamically adapt content delivery—such as serving lower-resolution assets to users on constrained networks—to optimize performance.

Accessing the Connection Object

The Network Information API is exposed through the navigator object in supported browsers via navigator.connection (or vendor-prefixed versions like navigator.mozConnection or navigator.webkitConnection).

const connection = navigator.connection || navigator.mozConnection || navigator.webkitConnection;

If the API is supported, this object provides several read-only properties containing metrics about the user’s connection bandwidth and latency.

Key Properties for Measuring Connection Speed

The API provides specific properties to quantify network speed and determine the user’s network capability:

• downlink: Represents the estimated effective bandwidth in megabits per second (Mbps), rounded to the nearest multiple of 25 kilobits per second to prevent fingerprinting.
• rtt: Represents the estimated round-trip time in milliseconds (ms), rounded to the nearest multiple of 25 milliseconds. It measures the duration between sending a request and receiving a response.
• effectiveType: Returns a string describing the connection quality based on a combination of rtt and downlink values. The possible values are 'slow-2g', '2g', '3g', and '4g'. This categorizes real-world performance rather than the physical connection technology (for example, a slow Wi-Fi connection might be categorized as '3g').
• saveData: A boolean indicating whether the user has enabled a “Data Saver” mode in their browser or operating system.

How the Browser Calculates Speed Metrics

The browser does not run active network speed tests to populate these values. Instead, it monitors the performance of recent network requests made by the browser.

1. Passive Observation: The browser observes the round-trip times and transfer rates of recently completed HTTP requests.
2. Smoothing and Estimation: It computes a weighted average of these recent samples to estimate overall throughput and latency.
3. Quantization: To protect user privacy and prevent fingerprinting, the raw measurements are bucketed into predefined ranges rather than exposing precise values.

Listening for Network Changes

Network conditions can fluctuate as users move or switch between connections (e.g., from Wi-Fi to cellular). The API provides a change event listener to monitor updates in real time.

if ('connection' in navigator) {
  function updateNetworkStatus() {
    console.log(`Effective Connection Type: ${navigator.connection.effectiveType}`);
    console.log(`Estimated Downlink: ${navigator.connection.downlink} Mbps`);
    console.log(`Estimated RTT: ${navigator.connection.rtt} ms`);
  }

  // Initial check
  updateNetworkStatus();

  // Listen for changes
  navigator.connection.addEventListener('change', updateNetworkStatus);
}

Practical Application: Adaptive Content Delivery

By evaluating the effectiveType or downlink value, JavaScript can conditionally load appropriately sized resources:

function loadMedia() {
  if (!navigator.connection) {
    // Fallback if API is unsupported
    loadStandardMedia();
    return;
  }

  if (navigator.connection.saveData || navigator.connection.effectiveType === 'slow-2g' || navigator.connection.effectiveType === '2g') {
    // Load low-resolution images or disable auto-playing videos
    loadLowBandwidthAssets();
  } else if (navigator.connection.effectiveType === '3g') {
    loadMediumBandwidthAssets();
  } else {
    // Fast connection (4G, 5G, or fast Wi-Fi)
    loadHighBandwidthAssets();
  }
}

Through this mechanism, the Network Information API gives applications the real-time context needed to make informed decisions about resource prioritization and performance optimization.