HomeGuidesReferenceLearn

Reference version

ArchiveExpo SnackDiscord and ForumsNewsletter

Expo Battery iconExpo Battery

GitHub

npm

A library that provides battery information for the physical device, as well as corresponding event listeners.


expo-battery provides battery information for the physical device (such as battery level, whether or not the device is charging, and more) as well as corresponding event listeners.

Platform Compatibility

Android DeviceAndroid EmulatoriOS DeviceiOS SimulatorWeb

Installation

Terminal
npx expo install expo-battery

If you're installing this in a bare React Native app, you should also follow these additional installation instructions.

Usage

Basic Battery Usage
import { useBatteryLevel } from 'expo-battery';
import { StyleSheet, Text, View } from 'react-native';

export default function App() {
  const batteryLevel = useBatteryLevel();

  return (
    <View style={styles.container}>
      <Text>Current Battery Level: {batteryLevel}</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    marginTop: 15,
    alignItems: 'center',
    justifyContent: 'center',
  },
});

API

import * as Battery from 'expo-battery';

Hooks

useBatteryLevel()

Gets the device's battery level, as in getBatteryLevelAsync.

Example

const batteryLevel = useBatteryLevel();

Returns

  • number

The battery level of the device.

useBatteryState()

Gets the device's battery state, as in getBatteryStateAsync.

Example

const batteryState = useBatteryState();

Returns

  • BatteryState

The battery state of the device.

useLowPowerMode()

Boolean that indicates if the device is in low power or power saver mode, as in isLowPowerModeEnabledAsync.

Example

const lowPowerMode = useLowPowerMode();

Returns

  • boolean

Returns a boolean indicating if the device is in low power mode.

usePowerState()

Gets the device's power state information, as in getPowerStateAsync.

Example

const { lowPowerMode, batteryLevel, batteryState } = usePowerState();

Returns

  • PowerState

Returns power state information.

Methods

getBatteryLevelAsync()

Gets the battery level of the device as a number between 0 and 1, inclusive. If the device does not support retrieving the battery level, this method returns -1. On web, this method always returns 1.

Example

await Battery.getBatteryLevelAsync();
// 0.759999

Returns

  • Promise<number>

A Promise that fulfils with a number between 0 and 1 representing the battery level, or -1 if the device does not provide it.

getBatteryStateAsync()

Tells the battery's current state. On web, this always returns BatteryState.UNKNOWN.

Example

await Battery.getBatteryStateAsync();
// BatteryState.CHARGING

Returns

  • Promise<BatteryState>

Returns a Promise which fulfills with a Battery.BatteryState enum value for whether the device is any of the four states.

getPowerStateAsync()

Gets the power state of the device including the battery level, whether it is plugged in, and if the system is currently operating in Power Saver Mode (Android) or Low Power Mode (iOS). This method re-throws any errors that occur when retrieving any of the power-state information.

Example

await Battery.getPowerStateAsync();
// {
//   batteryLevel: 0.759999,
//   batteryState: BatteryState.UNPLUGGED,
//   lowPowerMode: true,
// }

Returns

  • Promise<PowerState>

Returns a Promise which fulfills with PowerState object.

isAvailableAsync()

Resolves with whether the battery API is available on the current device. The value of this property is true on Android and physical iOS devices and false on iOS simulators. On web, it depends on whether the browser supports the web battery API.

Returns

  • Promise<boolean>

isBatteryOptimizationEnabledAsync()

Checks whether battery optimization is enabled for your application. If battery optimization is enabled for your app, background tasks might be affected when your app goes into doze mode state. (only on Android 6.0 or later)

Example

await Battery.isBatteryOptimizationEnabledAsync();
// true

Returns

  • Promise<boolean>

Returns a Promise which fulfills with a boolean value of either true or false, indicating whether the battery optimization is enabled or disabled, respectively. (Android only)

isLowPowerModeEnabledAsync()

Gets the current status of Power Saver mode on Android and Low Power mode on iOS. If a platform doesn't support Low Power mode reporting (like web, older Android devices), the reported low-power state is always false, even if the device is actually in low-power mode.

Example

Power Saver Mode (Android) or Low Power Mode (iOS) are enabled.

await Battery.isLowPowerModeEnabledAsync();
// true

Returns

  • Promise<boolean>

Returns a Promise which fulfills with a boolean value of either true or false, indicating whether low power mode is enabled or disabled.

Event Subscriptions

addBatteryLevelListener(listener)

NameTypeDescription
listener(event: BatteryLevelEvent) => void

A callback that is invoked when battery level changes. The callback is provided a single argument that is an object with a batteryLevel key.


Subscribe to the battery level change updates.

On Android devices, the event fires only when significant changes happens, which is when the battery level drops below android.intent.action.BATTERY_LOW or rises above android.intent.action.BATTERY_OKAY from a low battery level. See Monitor the Battery Level and Charging State in Android documentation for more information.

On iOS devices, the event fires when the battery level drops one percent or more, but is only fired once per minute at maximum.

On web, the event never fires.

Returns

  • Subscription

A Subscription object on which you can call remove() to unsubscribe from the listener.

addBatteryStateListener(listener)

NameTypeDescription
listener(event: BatteryStateEvent) => void

A callback that is invoked when battery state changes. The callback is provided a single argument that is an object with a batteryState key.


Subscribe to the battery state change updates to receive an object with a Battery.BatteryState enum value for whether the device is any of the four states.

On web, the event never fires.

Returns

  • Subscription

A Subscription object on which you can call remove() to unsubscribe from the listener.

addLowPowerModeListener(listener)

NameTypeDescription
listener(event: PowerModeEvent) => void

A callback that is invoked when Power Saver Mode (Android) or Low Power Mode (iOS) changes. The callback is provided a single argument that is an object with a lowPowerMode key.


Subscribe to Power Saver Mode (Android) or Low Power Mode (iOS) updates. The event fires whenever the power mode is toggled.

On web, the event never fires.

Returns

  • Subscription

A Subscription object on which you can call remove() to unsubscribe from the listener.

Types

BatteryLevelEvent

NameTypeDescription
batteryLevelnumber

A number between 0 and 1, inclusive, or -1 if the battery level is unknown.

BatteryStateEvent

NameTypeDescription
batteryStateBatteryState

An enum value representing the battery state.

PowerModeEvent

NameTypeDescription
lowPowerModeboolean

A boolean value, true if lowPowerMode is on, false if lowPowerMode is off.

PowerState

NameTypeDescription
batteryLevelnumber

A number between 0 and 1, inclusive, or -1 if the battery level is unknown.

batteryStateBatteryState

An enum value representing the battery state.

lowPowerModeboolean

A boolean value, true if lowPowerMode is on, false if lowPowerMode is off.

Subscription

NameTypeDescription
remove() => void

A method to unsubscribe the listener.

Enums

BatteryState

BatteryState Values

UNKNOWN

BatteryState.UNKNOWN = 0

If the battery state is unknown or inaccessible.

UNPLUGGED

BatteryState.UNPLUGGED = 1

If battery is not charging or discharging.

CHARGING

BatteryState.CHARGING = 2

If battery is charging.

FULL

BatteryState.FULL = 3

If the battery level is full.