Skip to main content

Battery Status

This plugin provides an implementation of an old version of the Battery Status Events API.

Online documentation

Cordova documentation

Installation​

Cordova​

cordova plugin add cordova-plugin-battery-status
npm install @awesome-cordova-library/batterystatus

Capacitor / Ionic​

npm install cordova-plugin-battery-status
npm install @awesome-cordova-library/batterystatus
npx cap sync

Vanilla​

Declaration​

class BatteryStatus {
  /**
   * Fires when the battery charge percentage changes by at least 1 percent, or when the device is plugged in or unplugged. Returns an object containing battery status.
   * @param callback {(batterystatus: BatteryStatusType) => void}
   */
  static onBatteryStatus(
    callback: (batterystatus: BatteryStatusType) => void
  ): void;
  /**
   * Fires when the battery charge percentage changes by at least 1 percent, or when the device is plugged in or unplugged. Returns an object containing battery status.
   * @param callback {(batterystatus: BatteryStatusType) => void}
   */
  static onBatteryStatusWeb(
    callback: (batterystatus: BatteryStatusType) => void
  ): void;
  /**
   * Fires when the battery charge percentage reaches the low charge threshold. This threshold value is device-specific.
   * Incompatible without cordova
   * @param callback {(batterystatus: BatteryStatusType) => void}
   */
  static onBatteryLow(
    callback: (batterystatus: BatteryStatusType) => void
  ): void;
  /**
   * Fires when the battery charge percentage reaches the critical charge threshold. This threshold value is device-specific.
   * Incompatible without cordova
   * @param callback {(batterystatus: BatteryStatusType) => void}
   */
  static onBatteryCritical(
    callback: (batterystatus: BatteryStatusType) => void
  ): void;
}

Usages​

import BatteryStatus from "@awesome-cordova-library/batterystatus";

BatteryStatus.onBatteryStatus((batterystatus) => {
  console.log(
    `Battery is plugged: ${batterystatus.isPlugged} // Battery level: ${batterystatus.level}`
  );
});

React​

Declaration​

const useBatteryStatus: () => {
  onBatteryStatus: (
    callback: (batterystatus: BatteryStatusType) => void
  ) => void;
  onBatteryLow: (callback: (batterystatus: BatteryStatusType) => void) => void;
  onBatteryCritical: (
    callback: (batterystatus: BatteryStatusType) => void
  ) => void;
};

Usages​

import { useEffect, useState } from "react";
import { BatteryStatusType } from "@awesome-cordova-library/batterystatus";
import useBatteryStatus from "@awesome-cordova-library/batterystatus/lib/react";

function App() {
  const [batteryStatus, setBatteryStatus] = useState<BatteryStatusType>();
  const { onBatteryStatus } = useBatteryStatus();

  useEffect(() => {
    onBatteryStatus((batterystatus) => {
      setBatteryStatus(batterystatus);
    });
  }, [onBatteryStatus]);

  return (
    <div>
      <p>Battery Is plugged: {String(batteryStatus?.isPlugged)}</p>
      <p>Battery level: {batteryStatus?.level}</p>
    </div>
  );
}