capacitor-thermal-state

Monitor device thermal state (overheating detection) for Capacitor apps. Works on iOS and Android. No configuration needed.

Install

npm install capacitor-thermal-state
npx cap sync

Usage

import { ThermalState } from 'capacitor-thermal-state'

// Get current state
const { state, headroom } = await ThermalState.getState()
// state: 'nominal' | 'fair' | 'serious' | 'critical' | 'unknown'
// headroom: 0.0–1.0 (Android API 31+) or null

// Listen for changes
const listener = await ThermalState.addListener(
  'thermalStateChange',
  ({ state, headroom }) => {
    if (state === 'serious') reduceLoad()
    if (state === 'critical') stopHeavyWork()
  }
)

// Remove listener
await listener.remove()

// Simulate heat for testing
await ThermalState.simulateHeat()

Thermal states

| State | Meaning | Recommended action | |----------|-----------------------------------|----------------------------| | nominal | Device is cool | Full performance OK | | fair | Slightly warm, no throttling | Monitor situation | | serious | Hot, system reducing performance | Reduce load | | critical | Very hot, heavy throttling | Stop all heavy operations | | unknown | Web platform or old Android | — |

API

getState()

Returns the current thermal state of the device.

getState(): Promise<ThermalStateResult>

simulateHeat()

Simulates a thermal state change event for testing purposes. Fires a thermalStateChange event with state serious.

simulateHeat(): Promise<void>

addListener('thermalStateChange', handler)

Listen for thermal state changes in real time.

addListener(
  eventName: 'thermalStateChange',
  listenerFunc: (state: ThermalStateResult) => void
): Promise<PluginListenerHandle>

removeAllListeners()

Remove all listeners for this plugin.

Interfaces

ThermalStateResult

| Property | Type | Description | |----------|------|-------------| | state | ThermalStateValue | Current thermal state | | headroom | number | null | Thermal headroom 0.0–1.0, Android API 31+ only |

Platform support

| Platform | Supported | Notes | |----------|-----------|-------| | Android | ✅ | API 29+ for state, API 31+ for headroom | | iOS | ✅ | iOS 11+ | | Web | ⚠️ | Always returns unknown |