Battery

Battery level, charging state, and low power mode

One.Battery reports the battery level, charging state, and low power mode, with one-shot reads, change listeners, and hooks. Reach for it to defer heavy work off battery, to warn before a long capture, or to dim optional effects in low power mode.

On iOS it reads UIDevice for level and state and ProcessInfo for low power mode. On Android it reads BatteryManager and the sticky battery intent, plus the power saver flag. On web the Battery Status API feeds reads and listeners where the browser has it.

Usage

import { useBatteryLevel } from 'one'

function Level() {
  const level = useBatteryLevel()
  return <>{level < 0 ? 'unknown' : `${Math.round(level * 100)}%`}</>
}

The hooks publish the one-shot read plus live updates: level, state, low power mode, and the combined power state. A level below zero means the device does not report one.

How it works

getLevel resolves 0 to 1, or -1 when the device reports no level. getState resolves unknown, unplugged, charging, full, or not charging, the last Android only. getPowerState reads level, state, and low power mode together. isLowPowerModeEnabled reports Power Saver on Android and Low Power Mode on iOS. isAvailable is synchronous: true on Android and physical iOS devices, false on iOS simulators.

Each listener takes one payload object: { batteryLevel }, { batteryState }, or { lowPowerMode }, and returns a subscription with remove. On Android the level event fires on significant changes only; on iOS it fires on drops of one percent or more, at most once per minute, so level UI updates in coarse steps by platform design.

On web, without the Battery Status API, reads resolve 1, unknown, and false, and listeners never fire. Android battery optimization exemptions are not part of this module.

API reference

The hooks useBatteryLevel, useBatteryState, useLowPowerMode, and usePowerState are named exports from one.

Platform differences

Limits and gotchas

• Level events are coarse. iOS throttles to a percent a minute and Android fires on significant changes only. Never animate from them.
• Minus one means unknown. Simulators and some hardware report no level. Show an unknown state instead of zero percent.
• notCharging is Android only. iOS never reports it; handle every state on both platforms.
• Low power mode is advisory. The OS will not enforce your response; shed optional work yourself when it flips on.

Examples

import { useEffect, useState } from 'react'
import { Text } from 'react-native'
import { One } from 'one'

function ExportWarning() {
  const [low, setLow] = useState(false)

  useEffect(() => {
    One.Battery.getPowerState().then((power) => {
      setLow(power.batteryLevel >= 0 && power.batteryLevel < 0.2)
    })
  }, [])

  if (!low) return null
  return <Text>Battery is low. Plug in before exporting.</Text>
}

One combined read answers the only question that matters here. The minus-one guard keeps unknown levels from triggering the warning.

import { useLowPowerMode } from 'one'

function Effects({ children }: { children: React.ReactNode }) {
  const lowPowerMode = useLowPowerMode()
  if (lowPowerMode) return null
  return <>{children}</>
}

The hook flips the moment the mode changes, so decorative layers drop out without any listener bookkeeping in the screen.