@gachlab/capacitor-keep-awake-plugin

A Capacitor plugin that prevents the device screen from sleeping. Works on Android, iOS, and Web.

| Platform | Implementation | |----------|---------------| | Android | FLAG_KEEP_SCREEN_ON window flag | | iOS | UIApplication.shared.isIdleTimerDisabled | | Web | Screen Wake Lock API |

Installation

npm install @gachlab/capacitor-keep-awake-plugin
npx cap sync

Usage

import { KeepAwake } from '@gachlab/capacitor-keep-awake-plugin';

// Prevent the screen from sleeping
await KeepAwake.dontAllowSleep();

// Check if keep-awake is active
const { isKeepAwake } = await KeepAwake.isKeepAwake();
console.log('Screen is kept awake:', isKeepAwake);

// Allow the screen to sleep again
await KeepAwake.allowSleep();

API

dontAllowSleep()

dontAllowSleep() => Promise<{ isAllowedSleep: boolean }>

Prevents the device screen from going to sleep. On Web, this requests a screen wake lock from the browser — the lock may be denied if the page is not visible or the device is low on battery.

Returns: { isAllowedSleep: false } when the screen is successfully kept awake. On Web, returns { isAllowedSleep: true } if the wake lock request was denied.

About the property name. isAllowedSleep describes whether the device is allowed to sleep. After a successful dontAllowSleep() call the screen is held awake, so sleeping is no longer allowed — that's why the property is false. On Web, a true here means the browser refused the wake lock and the screen can still sleep.

allowSleep()

allowSleep() => Promise<{ isAllowedSleep: boolean }>

Releases the keep-awake lock and allows the device screen to sleep normally.

Returns: { isAllowedSleep: true }

isKeepAwake()

isKeepAwake() => Promise<{ isKeepAwake: boolean }>

Checks whether the screen is currently being kept awake by this plugin.

Returns: { isKeepAwake: true } if the screen is being kept awake, { isKeepAwake: false } otherwise.

addListener('wakeLockReleased', ...)

addListener(
  eventName: 'wakeLockReleased',
  listenerFunc: (event: { reason: 'browser' | 'visibility' | 'system'; timestamp: number }) => void,
) => Promise<PluginListenerHandle>

Fires when an active wake lock is released by the system, not by an explicit allowSleep() call — so you learn the screen may now sleep without your consent. timestamp is the epoch time in milliseconds.

This is primarily a web signal: browsers drop the Screen Wake Lock when the page becomes hidden ('visibility') or under system pressure such as low battery ('browser'), and it must be re-requested. On Android/iOS the OS-level keep-awake is firm while the activity/scene lives, so the event does not fire there today ('system' is reserved for a future native break detector).

Platform Notes

Web

The Web implementation uses the Screen Wake Lock API. If the browser does not support it, dontAllowSleep() will silently fail and return { isAllowedSleep: true }. The wake lock is automatically released by the browser when the page becomes hidden.

Android

Uses FLAG_KEEP_SCREEN_ON on the activity window. This flag is cleared when the activity is destroyed. No special permissions are required.

iOS

Sets UIApplication.shared.isIdleTimerDisabled. The idle timer is re-enabled when the app is terminated. No special permissions are required.

Migration from v2

v3 introduces a breaking change in the return type property name:

- const { isAllowdSleep } = await KeepAwake.dontAllowSleep();
+ const { isAllowedSleep } = await KeepAwake.dontAllowSleep();

A new isKeepAwake() method is also available to query the current state.