npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@capawesome/capacitor-thermal-state

v0.1.2

Published

Capacitor plugin to read the device thermal state on Android and iOS.

Readme

Capacitor Thermal State Plugin

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

Features

  • 🌡️ 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!

Use Cases

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.

Compatibility

| Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.x.x | >=8.x.x | Active support |

Guides

Installation

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.

Android

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:

| Android Thermal Status | Thermal State | | --------------------------------------------------------------------------------------- | ------------- | | THERMAL_STATUS_NONE | nominal | | THERMAL_STATUS_LIGHT | fair | | THERMAL_STATUS_MODERATE | serious | | THERMAL_STATUS_SEVERE / THERMAL_STATUS_CRITICAL / THERMAL_STATUS_EMERGENCY / THERMAL_STATUS_SHUTDOWN | critical |

Configuration

No configuration required for this plugin.

Usage

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

Get the current thermal state

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;
};

Listen for thermal state changes

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

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();
};

API

getThermalState()

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('thermalStateChange', ...)

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.

| Param | Type | | ------------------ | ----------------------------------------------------------------------------------------------- | | eventName | 'thermalStateChange' | | listenerFunc | (event: ThermalStateChangeEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 0.1.0


removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.1.0


Interfaces

GetThermalStateResult

| Prop | Type | Description | Since | | ----------- | --------------------------------------------------------------- | ---------------------------------------- | ----- | | state | ThermalStateValue | The current thermal state of the device. | 0.1.0 |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

ThermalStateChangeEvent

| Prop | Type | Description | Since | | ----------- | --------------------------------------------------------------- | ---------------------------------------- | ----- | | state | ThermalStateValue | The current thermal state of the device. | 0.1.0 |

Type Aliases

ThermalStateValue

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'

Handling the Thermal State

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:

| State | Suggested App Reaction | | ---------- | -------------------------------------------------------------------------------------- | | nominal | No action needed. Run at full quality. | | fair | Reduce non-essential work, e.g. lower the prefetching rate. | | serious | Reduce the frame rate, pause prefetching, and defer background or ML work. | | critical | Reduce the workload as much as possible to help the device cool down. |

FAQ

Which platforms are supported by this plugin?

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.

Why does getThermalState reject on my Android device?

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.

What do the different thermal states mean?

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.

Why is the thermalStateChange event not emitted?

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).

Do I need any permissions or configuration to use this plugin?

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

Can I use this plugin with Ionic, React, Vue or Angular?

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.

Related Plugins

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

Newsletter

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

Changelog

See CHANGELOG.md.

License

See LICENSE.