Battery Status API in JavaScript Explained

The Battery Status API, also known as the Battery API, allows web developers to access system battery information and monitor changes in a device’s power levels using JavaScript. This article explains how the API works, the specific properties it exposes through the BatteryManager interface, how to implement it using modern JavaScript, and the real-world use cases along with privacy-related browser support considerations.

What Is the Battery Status API?

The Battery Status API provides a standardized way for web applications to determine the battery state of the hosting device. Accessed via the asynchronous method navigator.getBattery(), it returns a Promise that resolves with a BatteryManager object. This object contains data about the current power state, charging status, and remaining time before the battery is depleted or fully charged.

Core Properties of the BatteryManager Interface

The BatteryManager interface exposes four read-only properties:

• charging: A boolean value indicating whether the device is currently plugged into a power source (true) or running on battery (false).
• level: A number between 0.0 and 1.0 representing the current battery level. For example, 0.75 corresponds to 75% battery capacity.
• chargingTime: The time in seconds remaining until the battery is fully charged. It returns 0 if the battery is full or Infinity if the value is unknown or the device is discharging.
• dischargingTime: The time in seconds remaining until the battery is completely empty. It returns Infinity if the battery is charging or cannot be determined.

How to Read Battery Status with JavaScript

To read device power levels, use navigator.getBattery() to resolve the BatteryManager object and read its properties.

navigator.getBattery().then((battery) => {
  console.log(`Battery level: ${battery.level * 100}%`);
  console.log(`Is charging: ${battery.charging ? "Yes" : "No"}`);
  console.log(`Charging time: ${battery.chargingTime} seconds`);
  console.log(`Discharging time: ${battery.dischargingTime} seconds`);
});

Listening for Power Level Changes

The BatteryManager interface inherits from EventTarget, enabling event listeners to detect real-time changes in power status:

• levelchange: Fires when the battery percentage changes.
• chargingchange: Fires when the charging cable is connected or disconnected.
• chargingtimechange: Fires when the estimated time to full charge updates.
• dischargingtimechange: Fires when the estimated time until battery depletion updates.

navigator.getBattery().then((battery) => {
  // Update UI when battery percentage changes
  battery.addEventListener('levelchange', () => {
    console.log(`New battery level: ${battery.level * 100}%`);
  });

  // Update UI when charger is plugged/unplugged
  battery.addEventListener('chargingchange', () => {
    console.log(`Charging state changed: ${battery.charging}`);
  });
});

Practical Applications

Monitoring device power enables applications to dynamically optimize resource consumption:

• Battery-saving modes: Disabling heavy CSS animations, video auto-play, or background polling when the battery falls below a specific threshold (e.g., 20%).
• Data protection: Automatically triggering autosave routines for critical user data when the battery drops to critically low levels.
• Task scheduling: Postponing resource-intensive background synchronization or large file uploads until the device is plugged into power.

Browser Support and Privacy Concerns

While the API was designed to help conserve energy, it introduced user privacy and fingerprinting risks. High-precision battery readings allowed third-party trackers to correlate and identify user sessions across different browsing contexts.

As a result, major browsers handle the API differently:

• Chromium Browsers (Chrome, Edge, Opera): Support the API, but limit the precision of battery levels and time estimates to mitigate fingerprinting.
• Firefox and Safari: Removed support for the API to protect user privacy.

Before calling the API in production environments, always check for support:

if ('getBattery' in navigator) {
  navigator.getBattery().then((battery) => {
    // API is supported
  });
} else {
  // API is not supported on this browser
}