The Screen Wake Lock API allows web applications the ability to prevent the client device screen from locking or dimming after the configured timeout settings. This can be useful for web applications that require continuous user interaction, such as reading applications, video players, presentation tools or anything that requires real-time interaction.
The API is designed to be simple to use relying on promises to request and release wake locks as needed.
Key features of the Wake Lock API
Uninterrupted access to content
By using leveraging the Wake Lock API, developers can ensure that their clients maintain uninterrupted access to the content on the screen regardless of their system settings.
Wake lock types
The Wake Lock API currently supports a single wake type called "screen", however, that list could grow in the future to allow for potentially other kinds of locks.
Promise based API
The Wake Lock API relies on promises in order to request and to release wake locks.
Request a wake lock
You can request a Wake Lock by using the following method call of the navigator object:
let lock = await navigator.wakeLock.request('screen');
This will return a promise that resolves to a WakeLockSentinel object.
With this lock created, the browser will now ignore the configured timeout settings on the client machine and keep the client's laptop on until the lock has been released.
Release a wake lock
Once the user is done consuming the content that requires the screen to stay awake, you want to ensure that things go back to normal operations, and you can do that by calling the release method on the WakeLockSentinel object.
if (lock != null){
await lock.release();
lock = null;
}
Handling tab changes
If a user navigates away from a page that requires a lock, such as a video player, then ideally you want to be able to release the lock so that operations go back to their normal state.
And for that you can leverage the visibilitychange event in the document and monitor the visibilityState in order to request and release locks appropriately.
document.addEventListener('visibilitychange', async () => {
if (lock !== null && document.visibilityState === 'visible'){
lock = await navigator.wakeLock.request('screen');
}
else if (lock !== null){
await wakeLock.release();
lock = null;
}
});
Having multiple wake locks
You can indeed create multiple locks per application, however, you must ensure to release all locks in order for the client to revert back to its normal dimming behavior.
Example scenario
User opens tab 1: Requests a wake lock to play a video
User opens tab 2: Requests a lock to display real-time dashboard
Each of the tabs manages their own wake lock separately, and if you have the proper 'visibilitychange' event handler's in place, then ideally both tabs should be able to release their locks appropriately.
Consideration on battery life
Keeping the screen on at all times regardless of idling and timeouts, can of course decrease a client devices overall battery life. For that reason, it might be good to notify the user that the screen will remain on until they trigger a wakeLock release by navigating away from that particular page.
It's also good to be mindful of when you are implementing locks as well. While it might make sense to simply just have them on all the time to ensure that your application is constantly visible, anything that deviates from normal behavior and causes the user to question what is happening is typically not considered good UX.
Browser support
The Screen Wake Lock API is relatively new (as far as web standards go) however it is currently supported in all major browsers.
Walter Guevara is a software engineer, startup founder and currently teaches programming for a coding bootcamp. He is currently building things that don't yet exist.
Last updated on: