# Battery Status Plugin

Tested Version: [2.0.3](https://github.com/apache/cordova-plugin-battery-status/releases/tag/2.0.3)

{% hint style="info" %}
This document is based on the original Cordova docs available at [Cordova Docs](https://github.com/apache/cordova-plugin-battery-status).
{% endhint %}

## Plugin ID

```javascript
cordova-plugin-battery-status
```

## Adding the Plugin

In order to use this plugin, please [enable](https://en.docs.monaca.io/products_guide/monaca_ide/dependencies/cordova_plugin#import-cordova-plugins) `Battery` plugin in Monaca Cloud IDE.

## API Reference

### Status object

All events in this plugin return an object with the following properties:

| Property    | Type    | Description                                |
| ----------- | ------- | ------------------------------------------ |
| `level`     | Number  | The battery charge percentage (`0-100`)    |
| `isPlugged` | Boolean | Indicates whether the device is plugged in |

### batterystatus event

Fires when the battery charge percentage changes by at least `1 percent`, or when the device is plugged in or unplugged. Returns an [object](https://en.docs.monaca.io/reference/cordova_10.0/battery-status#status-object) containing battery status.

#### Example

```javascript
window.addEventListener("batterystatus", onBatteryStatus, false);

function onBatteryStatus(status) {
    console.log("Level: " + status.level + " isPlugged: " + status.isPlugged);
}
```

#### Supported Platforms

* iOS
* Android

#### Quirks: Android

{% hint style="info" %}
The Android implementations are greedy and prolonged use will drain the device's battery.
{% endhint %}

### batterylow event

Fires when the battery charge percentage reaches the low charge threshold. This threshold value is device-specific. Returns an [object](https://en.docs.monaca.io/reference/cordova_10.0/battery-status#status-object) containing battery status.

#### Example

```javascript
window.addEventListener("batterylow", onBatteryLow, false);

function onBatteryLow(status) {
    alert("Battery Level Low " + status.level + "%");
}
```

#### Supported Platforms

* iOS
* Android

### batterycritical event

Fires when the battery charge percentage reaches the critical charge threshold. This threshold value is device-specific. Returns an [object](https://en.docs.monaca.io/reference/cordova_10.0/battery-status#status-object) containing battery status.

#### Example

```javascript
window.addEventListener("batterycritical", onBatteryCritical, false);

function onBatteryCritical(status) {
    alert("Battery Level Critical " + status.level + "%\nRecharge Soon!");
}
```

#### Supported Platforms

* iOS
* Android