How to implement the Screen Wake Lock API in JavaScript

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.