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