Capacitor Keep Awake Plugin
Capacitor plugin to keep the screen awake.
Features
- 🌙 Keep awake: Prevent the screen from dimming or turning off.
- 💤 Allow sleep: Restore the default screen sleep behavior at any time.
- 🔍 State: Read whether the screen is currently kept awake.
- 🌐 Cross-platform: Supports Android, iOS and Web (via the Screen Wake Lock API).
- 🤝 Compatibility: Works alongside the Battery, Screen Brightness and Screen Orientation 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 Keep Awake plugin is typically used whenever the screen must stay visible without user interaction, for example:
- Media playback: Keep the screen on while users watch videos or follow along with content.
- Navigation and tracking: Prevent the display from turning off during turn-by-turn navigation or workout tracking.
- Hands-free reading: Keep recipes, sheet music, or step-by-step instructions visible while the user's hands are busy.
- Dashboards and kiosks: Display live data or presentations without the screen dimming or sleeping.
Compatibility
| Plugin Version | Capacitor Version | Status |
|---|---|---|
| 0.x.x | >=8.x.x | Active support |
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-keep-awake` plugin in my project.
If you prefer Manual Setup, install the plugin by running the following commands:
npm install @capawesome/capacitor-keep-awake
npx cap sync
This plugin is available on Android, iOS and Web. No additional permissions or configuration are required.
Configuration
No configuration required for this plugin.
Usage
The following examples show how to keep the screen awake, allow it to sleep again, check whether it is currently kept awake, and check whether the feature is available.
Keep the screen awake
Prevent the screen from dimming or turning off. The screen is kept awake until allowSleep(...) is called or the app is restarted. This only affects your app and is not a system-wide setting:
import { KeepAwake } from '@capawesome/capacitor-keep-awake';
const keepAwake = async () => {
await KeepAwake.keepAwake();
};
Allow the screen to sleep again
Restore the default screen sleep behavior at any time:
import { KeepAwake } from '@capawesome/capacitor-keep-awake';
const allowSleep = async () => {
await KeepAwake.allowSleep();
};
Check if the screen is kept awake
Read whether the screen is currently kept awake:
import { KeepAwake } from '@capawesome/capacitor-keep-awake';
const isKeptAwake = async () => {
const { keptAwake } = await KeepAwake.isKeptAwake();
return keptAwake;
};
Check if the feature is available
On the Web, keeping the screen awake depends on whether the browser supports the Screen Wake Lock API. On Android and iOS, this always returns true:
import { KeepAwake } from '@capawesome/capacitor-keep-awake';
const isAvailable = async () => {
const { available } = await KeepAwake.isAvailable();
return available;
};
API
allowSleep()
allowSleep() => Promise<void>
Allow the screen to dim or turn off again.
This reverses the effect of keepAwake(...).
Only available on Android, iOS and Web.
Since: 0.1.0
isAvailable()
isAvailable() => Promise<IsAvailableResult>
Check if keeping the screen awake is available on this device.
On Web, this depends on whether the browser supports the
Screen Wake Lock API.
On Android and iOS, this always returns true.
Only available on Android, iOS and Web.
Returns: Promise<IsAvailableResult>
Since: 0.1.0
isKeptAwake()
isKeptAwake() => Promise<IsKeptAwakeResult>
Check if the screen is currently kept awake.
Only available on Android, iOS and Web.
Returns: Promise<IsKeptAwakeResult>
Since: 0.1.0
keepAwake()
keepAwake() => Promise<void>
Keep the screen awake by preventing it from dimming or turning off.
The screen is kept awake until allowSleep(...) is called or the app is
restarted. This setting only affects your app and is not system-wide.
Only available on Android, iOS and Web.
Since: 0.1.0
Interfaces
IsAvailableResult
| Prop | Type | Description | Since |
|---|---|---|---|
available | boolean | Whether keeping the screen awake is available on this device or not. | 0.1.0 |
IsKeptAwakeResult
| Prop | Type | Description | Since |
|---|---|---|---|
keptAwake | boolean | Whether the screen is currently kept awake or not. | 0.1.0 |
Behavior
Keep the following in mind when using this plugin:
- App scope: Keeping the screen awake only affects your app and is not a system-wide setting.
- State reset: The screen is only kept awake until
allowSleep(...)is called or the app is restarted. - Web auto-release: On the Web, the underlying Screen Wake Lock is automatically released by the browser whenever the tab becomes hidden (for example, when the user switches tabs or minimizes the window). The plugin automatically re-acquires the wake lock once the tab becomes visible again, as long as
allowSleep(...)has not been called in the meantime.
FAQ
How is this plugin different from other similar plugins?
It keeps the screen awake on Android, iOS, and the Web from one fully typed API, and lets you check both whether the feature is available and whether the screen is currently kept awake. On the Web it uses the Screen Wake Lock API and automatically re-acquires the lock when a hidden tab becomes visible again, so the behavior stays predictable across platforms. It needs no permissions or configuration and is actively maintained against the latest Capacitor version.
Which platforms does this plugin support?
The plugin supports Android, iOS and Web. On the Web, it relies on the Screen Wake Lock API, so availability depends on the browser. You can check this at runtime with the isAvailable() method, which always returns true on Android and iOS.
Does keeping the screen awake affect other apps?
No, keeping the screen awake only affects your app and is not a system-wide setting. As soon as the user leaves your app, the default screen sleep behavior of the device applies again.
How long is the screen kept awake?
The screen is kept awake until allowSleep(...) is called or the app is restarted. The setting is not persisted across app restarts.
Why does the screen sleep again on the Web after switching tabs?
On the Web, the browser automatically releases the underlying wake lock whenever the tab becomes hidden, for example when the user switches tabs or minimizes the window. The plugin automatically re-acquires the wake lock once the tab becomes visible again, as long as allowSleep(...) has not been called in the meantime. See the Behavior section for details.
Do I need any permissions or configuration?
No, the plugin does not require any permissions or configuration on any platform. Simply install it and call keepAwake().
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.
- Screen Brightness: Read and control the screen brightness.
- Screen Orientation: Lock and unlock the screen orientation.
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.