battery

Track the device battery with the Battery Status API.


Package	`@vizejs/composable/battery`
Own the source	`vize lib pull composable:battery`
Runtime exports	`useBattery`
Gzip budget	1792 B

Usage

import { useBattery } from "@vizejs/composable/battery";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useBattery`	system	experimental	deterministic-fallback	stable	reactive-scope	web, desktop	`window`	`tryOnScopeDispose`

API

`useBattery`

Track the device battery with the Battery Status API. Server renders (and unsupported browsers) expose a full, charging battery (level: 1, charging: true, times 0/Infinity), which is the least alarming deterministic default. Late resolutions after the host changed or the scope stopped are ignored, and listeners are removed with the owning reactive scope.

function useBattery(options: UseBatteryOptions = {}): BatteryControls

Types

`BatteryManagerLike`

Subset of the Battery Status API BatteryManager.

Member	Type	Description
`charging`	`boolean`	Whether the battery is charging.
`chargingTime`	`number`	Seconds until fully charged (`Infinity` when discharging).
`dischargingTime`	`number`	Seconds until empty (`Infinity` when charging).
`level`	`number`	Charge level in `[0, 1]`.

`BatteryHost`

Navigator-like capability used by useBattery.

Member	Type	Description
`getBattery`?	`() => Promise<BatteryManagerLike>`	Resolve the battery manager, where supported.

`UseBatteryOptions`

Options for useBattery.

Member	Type	Description
`host`?	`MaybeRefOrGetter<BatteryHost \| null \| undefined>`	Reactive navigator capability for alternate runtimes and tests.

`BatteryControls`

Reactive battery state returned by useBattery.

Member	Type	Description
`isSupported`	`Readonly<Ref<boolean>>`	Whether the host exposes `getBattery`. `false` during server rendering.
`isReady`	`Readonly<Ref<boolean>>`	Whether the battery manager has resolved.
`charging`	`Readonly<Ref<boolean>>`	Whether the battery is charging.
`chargingTime`	`Readonly<Ref<number>>`	Seconds until fully charged.
`dischargingTime`	`Readonly<Ref<number>>`	Seconds until empty.
`level`	`Readonly<Ref<number>>`	Charge level in `[0, 1]`.
`error`	`Readonly<ShallowRef<unknown>>`	Rejection from `getBattery`, if any (for example a permissions policy).