Expo BatteryA 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 Device | Android Emulator | iOS Device | iOS Simulator | Web |
|---|---|---|---|---|
Installation
- npx expo install expo-batteryIf you're installing this in a bare React Native app, you should also follow these additional installation instructions.
Usage
import { useEffect, useState, useCallback } from 'react';
import * as Battery from 'expo-battery';
import { StyleSheet, Text, View } from 'react-native';
export default function App() {
const [batteryLevel, setBatteryLevel] = useState(null);
const [subscription, setSubscription] = useState(null);
const subscribe = async () => {
const batteryLevel = await Battery.getBatteryLevelAsync();
setBatteryLevel(batteryLevel);
setSubscription(
Battery.addBatteryLevelListener(({ batteryLevel }) => {
setBatteryLevel(batteryLevel);
console.log('batteryLevel changed!', batteryLevel);
})
);
};
const _unsubscribe = useCallback(() => {
subscription && subscription.remove();
setSubscription(null);
}, [subscription]);
useEffect(() => {
subscribe();
return () => unsubscribe();
}, []);
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';
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
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 Low Power Mode (iOS) or Power Saver Mode (Android). 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
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 Low Power mode on iOS and Power Saver mode on Android. 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
Low Power Mode (iOS) or Power Saver Mode (Android) 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, respectively.
Event Subscriptions
addBatteryLevelListener(listener)
| Name | Type | Description |
|---|---|---|
| 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 |
Subscribe to the battery level change updates.
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 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 here
to read more from the Android docs.
On web, the event never fires.
Returns
A Subscription object on which you can call remove() to unsubscribe from the listener.s
addBatteryStateListener(listener)
| Name | Type | Description |
|---|---|---|
| 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 |
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
A Subscription object on which you can call remove() to unsubscribe from the listener.
addLowPowerModeListener(listener)
| Name | Type | Description |
|---|---|---|
| listener | (event: PowerModeEvent) => void | A callback that is invoked when Low Power Mode (iOS) or Power Saver Mode (Android)
changes. The callback is provided a single argument that is an object with a |
Subscribe to Low Power Mode (iOS) or Power Saver Mode (Android) updates. The event fires whenever the power mode is toggled.
On web, the event never fires.
Returns
A Subscription object on which you can call remove() to unsubscribe from the listener.
Types
BatteryLevelEvent
| Name | Type | Description |
|---|---|---|
| batteryLevel | number | A number between |
BatteryStateEvent
| Name | Type | Description |
|---|---|---|
| batteryState | BatteryState | An enum value representing the battery state. |
PowerModeEvent
| Name | Type | Description |
|---|---|---|
| lowPowerMode | boolean | A boolean value, |
PowerState
| Name | Type | Description |
|---|---|---|
| batteryLevel | number | A number between |
| batteryState | BatteryState | An enum value representing the battery state. |
| lowPowerMode | boolean | A boolean value, |
Subscription
| Name | Type | Description |
|---|---|---|
| remove | () => void | - |
Enums
BatteryState
BatteryState Values