## Requirements and use cases This document describes an API that addresses two specific requirements: ### Provide an interface for determining the [connection type](https://wicg.github.io/netinfo/#dfn-connection-types) currently used to communicate with the network. It should be queryable in an ad hoc fashion from client pages, and should also be available in other contexts, like exposed to [service workers](https://w3c.github.io/ServiceWorker/v1/). **Example use cases:** * A web application whose primary purpose is to stream media could check `navigator.connection.type` prior to playback. When it's set to `'cellular'`, it could advise users that their mobile network operator might be charging for the bandwidth, and only start automatic playback of previously cached content. * A web application that makes use of a service worker to [cache](https://w3c.github.io/ServiceWorker/v1/#cache-objects) resources during [installation](https://w3c.github.io/ServiceWorker/v1/#installation-algorithm) might have different bundles of assets that it might cache: a list of crucial assets that are cached unconditionally, and a bundle of larger, optional assets that are only cached ahead of time when `navigator.connection.type` is `'ethernet'` or `'wifi'`. * A web application that uses a service worker with a [background sync](https://github.com/WICG/BackgroundSync/blob/master/explainer.md) handler might check the current `navigator.connection.type` value, and only transfer data inside the `sync` event handler if it is is `'ethernet'` or `'wifi'`. * A web application might make decision to enable offline mode based on network condition (e.g., when EDGE is not enough). ### Provide a way for scripts to be notified if the connection type changes. This allows developers to make dynamic changes to their user interface to inform the user that the network connection type has changed, and that it could impact them in some way. It also allows applications that were deferring the transfer of large amounts of data to automatically begin once a high-bandwidth network is detected. **Example use cases:** * A web application whose primary purpose is to stream media could dynamically change its user interface in response to updates to the connection type. This may afford a better user experience than waiting until a user attempts to playback and performing a one-off query. It allows applications to provide context about the connection in advance of user interaction. * A web application that allows for uploads or downloads might defer initiating the request when `navigator.connection.type` is set to `'cellular'`, and add a listener for changes to the connection. When a change to a high-bandwidth network type is detected, the request could be automatically started.

  // Get the connection type.
  var type = navigator.connection.type;

  // Get an upper bound on the downlink speed of the first network hop
  var max = navigator.connection.downlinkMax;

  function changeHandler(e) {
    // Handle change to connection here.
  }

  // Register for event changes.
  navigator.connection.onchange = changeHandler;

  // Alternatively.
  navigator.connection.addEventListener('change', changeHandler);
  

bluetooth

A Bluetooth connection.

cellular

A cellular connection (e.g., EDGE, HSPA, LTE, etc.).

ethernet

An Ethernet connection.

none

No network connection. The user agent will not contact the network when the user follows links or when a script requests a remote page (or knows that such an attempt would fail) - i.e., equivalent to navigator.onLine === false in HTML.

mixed

The user agent is using multiple connection types.

other

The connection type that is known, but not one of enumerated connection types.

unknown

The user agent has established a network connection, but is unable, or unwilling, to determine the underlying connection technology.

wifi

A Wi-Fi connection.

wimax

A WiMAX connection.

  enum ConnectionType {
    "bluetooth",
    "cellular",
    "ethernet",
    "mixed",
    "none",
    "other",
    "unknown",
    "wifi",
    "wimax"
  };

  enum EffectiveConnectionType {
    "2g",
    "3g",
    "4g",
    "slow-2g"
  };

  interface mixin NavigatorNetworkInformation {
    [SameObject] readonly attribute NetworkInformation connection;
  };

  Navigator includes NavigatorNetworkInformation;
  WorkerNavigator includes NavigatorNetworkInformation;

  [Exposed=(Window,Worker)]
  interface NetworkInformation : EventTarget {
    readonly attribute ConnectionType type;
    readonly attribute EffectiveConnectionType effectiveType;
    readonly attribute Megabit downlinkMax;
    readonly attribute Megabit downlink;
    readonly attribute Millisecond rtt;
    attribute EventHandler onchange;
  };

  typedef unrestricted double Megabit;
  typedef unsigned long long Millisecond;