BrowserBeginnerSSR-safehooks/browser/useBattery.ts

useBattery

Battery Status API.

Import

TypeScript
import { useBattery } from '@/hooks';

API

Signature

useBattery() → BatteryState

When to use

Use useBattery instead of re-implementing the same pattern in multiple components.

SSR / Next.js

Returns defaults on the server; hydrates on the client.

Live playground

Edit the example and see it run against the real @/hooks package in this app.

Live playgroundEdit · run with real @/hooks · useBattery
Editor
function Battery() {
  const b = useBattery();
  if (!b.supported) return <p>Battery API N/A</p>;
  return <p>{Math.round((b.level ?? 0) * 100)}% {b.charging ? '⚡' : ''}</p>;
}
Preview

Implementation source

Full library source for useBattery — copy into your project when you are not installing a package yet.

hooks/browser/useBattery.ts
import { useEffect, useState } from 'react';
import { hasNavigator, isBrowser } from '../utility/isBrowser';

export interface BatteryState {
  supported: boolean;
  loading: boolean;
  charging: boolean;
  chargingTime: number | null;
  dischargingTime: number | null;
  level: number | null;
}

type BatteryManager = EventTarget & {
  charging: boolean;
  chargingTime: number;
  dischargingTime: number;
  level: number;
};

/** Battery Status API when available. */
export function useBattery(): BatteryState {
  const [state, setState] = useState<BatteryState>({
    supported: false,
    loading: true,
    charging: false,
    chargingTime: null,
    dischargingTime: null,
    level: null,
  });

  useEffect(() => {
    if (!isBrowser() || !hasNavigator()) {
      setState((s) => ({ ...s, loading: false, supported: false }));
      return;
    }

    const nav = navigator as Navigator & {
      getBattery?: () => Promise<BatteryManager>;
    };

    if (!nav.getBattery) {
      setState((s) => ({ ...s, loading: false, supported: false }));
      return;
    }

    let battery: BatteryManager | null = null;
    let cancelled = false;

    const update = () => {
      if (!battery || cancelled) return;
      setState({
        supported: true,
        loading: false,
        charging: battery.charging,
        chargingTime: battery.chargingTime,
        dischargingTime: battery.dischargingTime,
        level: battery.level,
      });
    };

    nav.getBattery().then((b) => {
      if (cancelled) return;
      battery = b;
      update();
      b.addEventListener('chargingchange', update);
      b.addEventListener('levelchange', update);
      b.addEventListener('chargingtimechange', update);
      b.addEventListener('dischargingtimechange', update);
    });

    return () => {
      cancelled = true;
      if (battery) {
        battery.removeEventListener('chargingchange', update);
        battery.removeEventListener('levelchange', update);
        battery.removeEventListener('chargingtimechange', update);
        battery.removeEventListener('dischargingtimechange', update);
      }
    };
  }, []);

  return state;
}

Copy-paste example

useBattery.example.tsx
'use client';

import { useBattery } from '@/hooks';

export function Battery() {
  const b = useBattery();
  if (!b.supported) return <p>Battery API N/A</p>;
  return <p>{Math.round((b.level ?? 0) * 100)}% {b.charging ? '⚡' : ''}</p>;
}

Production checklist

  • Called only from Client Components or other custom hooks
  • Type parameters filled in (e.g. useFetch<User[]>)
  • Tip: Values are safe during SSR (defaults). Gate layout-dependent UI with useMounted when needed.
  • Source of truth: open hooks/browser/useBattery.ts for implementation details