Capacitor plugin to read the device thermal state and react before the operating system throttles your app.

• 🌡️ Thermal state: Read the current thermal state of the device.
• 🔔 Change events: Get notified whenever the thermal state changes.
• 🤝 Compatibility: Works alongside the Battery and Device Info plugins.
• 📦 CocoaPods & SPM: Supports CocoaPods and Swift Package Manager for iOS.
• 🔁 Up-to-date: Always supports the latest Capacitor version.

Missing a feature? Just open an issue and we'll take a look!

The Thermal State plugin is typically used to adapt an app's workload to the device's thermal condition, for example:

• Video and streaming apps: Lower the video quality or frame rate when the thermal state becomes serious.
• Games and 3D rendering: Reduce graphical effects to help the device cool down before the operating system throttles the app.
• Machine learning: Defer on-device ML inference or other background work while the thermal state is elevated.
• Data prefetching: Reduce the prefetching rate or pause background sync when the device gets warm.

• The Complete Guide to Capacitor Device Sensors: How to gate heavy work like video processing or ML inference before the OS throttles your app.

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-thermal-state` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capawesome/capacitor-thermal-state
npx cap sync

This plugin is available on Android and iOS. On the web, all methods reject as unimplemented.

Reading the thermal state requires Android 10 (API level 29) or newer. On older versions, getThermalState(...) rejects as unavailable and the thermalStateChange event is never emitted.

The Android thermal status values are mapped to the four common thermal states as follows:

No configuration required for this plugin.

The following examples show how to get the current thermal state, listen for thermal state changes, and remove all listeners.

Read the current thermal state of the device, for example to decide how much work your app should perform. Only available on Android (API level 29+) and iOS:

import { ThermalState } from '@capawesome/capacitor-thermal-state';

const getThermalState = async () => {
  const { state } = await ThermalState.getThermalState();
  return state;
};

Get notified whenever the thermal state of the device changes. The device is only observed while at least one listener is attached. Only available on Android (API level 29+) and iOS:

import { ThermalState } from '@capawesome/capacitor-thermal-state';

const addThermalStateChangeListener = async () => {
  await ThermalState.addListener('thermalStateChange', event => {
    console.log(event.state);
  });
};

Remove all listeners for this plugin when you no longer need to observe the thermal state:

import { ThermalState } from '@capawesome/capacitor-thermal-state';

const removeAllListeners = async () => {
  await ThermalState.removeAllListeners();
};

• getThermalState()
• addListener('thermalStateChange', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

getThermalState() => Promise<GetThermalStateResult>

Get the current thermal state of the device.

Only available on Android (API level 29+) and iOS.

Returns: Promise<GetThermalStateResult>

Since: 0.1.0

addListener(eventName: 'thermalStateChange', listenerFunc: (event: ThermalStateChangeEvent) => void) => Promise<PluginListenerHandle>

Listen for changes to the thermal state of the device.

The device is only observed while at least one listener is attached.

Only available on Android (API level 29+) and iOS.

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.1.0

The thermal state of the device.

• critical: The thermal state is significantly impacting performance. Reduce the workload as much as possible.
• fair: The thermal state is slightly elevated. Consider reducing non-essential work.
• nominal: The thermal state is within normal limits. No action is needed.
• serious: The thermal state is high. Reduce the workload to help the device cool down.

'critical' | 'fair' | 'nominal' | 'serious'

Use the thermal state to progressively reduce your app's workload before the operating system throttles it. The following table lists suggested reactions for each state:

The plugin is available on Android and iOS. On Android, reading the thermal state requires Android 10 (API level 29) or newer. On the web, all methods reject as unimplemented.

Reading the thermal state requires Android 10 (API level 29) or newer. On older Android versions, getThermalState(...) rejects as unavailable and the thermalStateChange event is never emitted.

The plugin reports one of four states: nominal means the thermal state is within normal limits, fair means it is slightly elevated, serious means it is high and the workload should be reduced, and critical means performance is significantly impacted and the workload should be reduced as much as possible. See Handling the Thermal State for suggested reactions to each state.

The device is only observed while at least one listener is attached, so make sure you have added a listener for the thermalStateChange event. Also note that the event is never emitted on Android versions older than Android 10 (API level 29).

No, the plugin does not require any permissions or configuration. Simply install it and call its methods.

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

• Battery: Access battery information of the device.
• Device Info: Read device information such as the model, manufacturer, operating system, and memory.

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

See CHANGELOG.md.

See LICENSE.