Introducing the Battery Status API

Mobile devices represent an increasingly large segment of all Web traffic. This traffic is so substantial, that APIs and design practices have been created specifically to cater to mobile devices. An example of this is the W3C’s Battery Status API, which allows an application to inspect the state of the device’s battery. This article explores the relatively new API, and shows you how to begin incorporating it into your applications today.

Detecting Support

The Battery Support API is still primarily unsupported. Therefore, you must verify that it exists before trying to use it. The following function returns a Boolean value, indicating whether or not the user’s browser supports the API. The function checks for the existence of the navigator.battery object. If it does not exist, it also checks for the Mozilla specific mozBattery object. I’ve seen code that also checks for webkitBattery, but I haven’t been able to verify it’s existence in Chrome.

function isBatteryStatusSupported() {
  return !!(navigator.battery || navigator.mozBattery);
}

Inspecting the Battery

If the battery object exists, it will contain the following four read only properties.

charging – This Boolean value indicates whether or not the system’s battery is currently charging. If the system doesn’t have a battery, or the value cannot be determined, then this will be true.
chargingTime – This numeric value represents the amount of time in seconds remaining until the battery is fully charged. chargingTime is set to zero if the battery is full, or if the system has no battery. If the system is not charging, or is unable to determine the amount of time remaining, then this is set to Infinity.
dischargingTime – Similar to chargingTime, this value represents the number of seconds remaining until the battery is fully discharged and the system becomes suspended. If the discharge time cannot be determined, there is no battery, or the battery is charging, then this value is set to Infinity.
level – This numeric value represents the current battery level. The value ranges from 0 to 1.0, and corresponds to the percentage of remaining battery life. A value of 1.0 indicates that either the battery is fully charged, there is no battery, or the level could not be determined.

Detecting Battery Events

Each of the previously discussed properties is tied to a battery event. These events are used to identify changes in the battery’s state. For example, plugging in the system would cause charging to transition from false to true. The four types of battery events are listed below.

chargingchange – This type of event is fired when charging is updated. These events can be handled with the onchargingchange() event handler.
chargingtimechange – These events are fired when chargingTime is updated. These events can be handled by the onchargingtimechange() event handler.
dischargingtimechange – When dischargingTime is updated, a dischargingtimechange event is fired. These events can be handled by the ondischargingtimechange() event handler.
levelchange – Updates to level cause these events to be fired. They can be handled using the onlevelchange() event handler.

Demo Page

The following code shows how to use the Battery Status API properties and events. The example page displays the value of each property, and updates them as events occur. The page is also available online.

<!DOCTYPE html>
<html lang="en">
<head>
  <title>The Battery Status API - Example</title>
  <meta charset="UTF-8" />
  <script>
    window.addEventListener("load", function() {
      var battery = navigator.battery || navigator.mozBattery;

      function displayBatteryStats() {
        document.getElementById("charging").textContent = (battery.charging) ? "charging" : "not charging";
        document.getElementById("chargingtime").textContent = battery.chargingTime;
        document.getElementById("dischargingtime").textContent = battery.dischargingTime;
        document.getElementById("level").textContent = battery.level * 100;
      }

      if (battery) {
        displayBatteryStats();
        battery.addEventListener("chargingchange", displayBatteryStats, false);
        battery.addEventListener("chargingtimechange", displayBatteryStats, false);
        battery.addEventListener("dischargingtimechange", displayBatteryStats, false);
        battery.addEventListener("levelchange", displayBatteryStats, false);
      } else {
        document.getElementById("stats").textContent = "Sorry, your browser does not support the Battery Status API";
      }
    }, false);
  </script>
</head>
<body>
  <div id="stats">
    Your battery is currently <span id="charging"></span>.<br />
    Your battery will be charged in <span id="chargingtime"></span> seconds.<br />
    Your battery will be discharged in <span id="dischargingtime"></span> seconds.<br />
    Your battery level is <span id="level"></span>%.
  </div>
</body>
</html>

Conclusion

This article has provided a complete rundown of the Battery Status API. Although support is not widespread yet, it’s only a matter of time. Given the proliferation of the mobile Web, developers should begin incorporating the battery into their designs as soon as possible.