Skip to content

useBattery

Hook to monitor device battery status using the Battery Status API.

Usage

tsx
import React from "react";
import { useBattery } from 'vhooks';

const BatteryDemo: React.FC = () => {
  const battery = useBattery();

  if (!battery.supported) {
    return <div>Your browser does not support the Battery Status API.</div>;
  }

  if (battery.loading) {
    return <div>Loading battery status...</div>;
  }

  return (
    <div>
      <h2>Battery Status</h2>
      <p>
        Level:{" "}
        {battery.level !== null
          ? `${(battery.level * 100).toFixed(0)}%`
          : "N/A"}
      </p>
      <p>Charging: {battery.charging ? "Yes" : "No"}</p>
      <p>
        Charging Time:{" "}
        {battery.chargingTime !== null
          ? `${battery.chargingTime} seconds`
          : "N/A"}
      </p>
      <p>
        Discharging Time:{" "}
        {battery.dischargingTime !== null
          ? `${battery.dischargingTime} seconds`
          : "N/A"}
      </p>
    </div>
  );
};

export default BatteryDemo;

Installation

sh
pnpm dlx scaflo@latest https://raw.githubusercontent.com/programming-with-ia/vDocs/scaflos/hooks/useBattery.json -e %src%/hooks
sh
npx scaflo@latest https://raw.githubusercontent.com/programming-with-ia/vDocs/scaflos/hooks/useBattery.json -e %src%/hooks
sh
bunx scaflo@latest https://raw.githubusercontent.com/programming-with-ia/vDocs/scaflos/hooks/useBattery.json -e %src%/hooks
sh
yarn dlx scaflo@latest https://raw.githubusercontent.com/programming-with-ia/vDocs/scaflos/hooks/useBattery.json -e %src%/hooks

API

useBattery(): BatteryState

Hook to monitor device battery status using the Battery Status API.

Returns

BatteryState

Current battery status information.

Type aliases

Ƭ BatteryState: Object

Battery state returned by the useBattery hook.

Type declaration

NameTypeDescription
chargingboolean | nullWhether the device is charging or null if unavailable.
chargingTimenumber | nullTime remaining until fully charged, in seconds, or null if unavailable.
dischargingTimenumber | nullTime remaining until fully discharged, in seconds, or null if unavailable.
levelnumber | nullCurrent battery level (0 to 1) or null if unavailable.
loadingbooleanWhether battery information is still loading.
supportedbooleanWhether the Battery API is supported.

Hook

ts
import { useState, useEffect } from "react";

type BatteryManager = {
    level: number;
    charging: boolean;
    chargingTime: number;
    dischargingTime: number;
    addEventListener(
    type: string,
    listener: EventListener | EventListenerObject | null,
    options?: boolean | AddEventListenerOptions
  ): void;
    removeEventListener(
    type: string,
    listener: EventListener | EventListenerObject | null,
    options?: boolean | EventListenerOptions
  ): void;
};

type BatteryState = {
    supported: boolean;
    loading: boolean;
    level: number | null;
    charging: boolean | null;
    chargingTime: number | null;
    dischargingTime: number | null;
};

type NavigatorWithBattery = Navigator & {
    getBattery: () => Promise<BatteryManager>;
};

export const useBattery = (): BatteryState => {
  const [batteryState, setBatteryState] = useState<BatteryState>({
    supported: false,
    loading: true,
    level: null,
    charging: null,
    chargingTime: null,
    dischargingTime: null,
  });

  useEffect(() => {
    const _navigator = navigator as NavigatorWithBattery;
    let battery: BatteryManager;

    const handleBatteryChange = () => {
      setBatteryState({
        supported: true,
        loading: false,
        level: battery.level,
        charging: battery.charging,
        chargingTime: battery.chargingTime,
        dischargingTime: battery.dischargingTime,
      });
    };

    if (!_navigator.getBattery) {
      setBatteryState((batteryState) => ({
        ...batteryState,
        supported: false,
        loading: false,
      }));
      return;
    }

    _navigator.getBattery().then((_battery) => {
      battery = _battery;
      handleBatteryChange();

      _battery.addEventListener("levelchange", handleBatteryChange);
      _battery.addEventListener("chargingchange", handleBatteryChange);
      _battery.addEventListener("chargingtimechange", handleBatteryChange);
      _battery.addEventListener("dischargingtimechange", handleBatteryChange);
    });

    return () => {
      if (!battery) return;
      battery.removeEventListener("levelchange", handleBatteryChange);
      battery.removeEventListener("chargingchange", handleBatteryChange);
      battery.removeEventListener("chargingtimechange", handleBatteryChange);
      battery.removeEventListener("dischargingtimechange", handleBatteryChange);
    };
  }, []);

  return batteryState;
};

vDocs