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 · useBatteryEditor
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.tsfor implementation details