DEV Community

Cover image for The Screen Wake Lock API
Michael Esteban
Michael Esteban

Posted on • Updated on

The Screen Wake Lock API

Chrome v84, released on 14th July, brought with it the Screen Wake Lock API - a way for developers to stop a device's screen from dimming and turning off. Previously this functionality was only possible by using a native app or a clever but hacky workaround such as NoSleep.js that continuously plays a hidden video on the webpage [UPDATE: NoSleep.js now includes support for the native API]. With the release of v84, an always on display can now be triggered natively in the browser.

Progressive Web Applications in particular stand to profit from this new API, as Microsoft and Google recently announced their commitment to forge ahead with improving the PWA experience. The types of use cases that could benefit include waiting to scan a boarding pass, presentation slides, recipe pages and e-books.

Requesting a screen wake lock is achieved through a single method call.

navigator.wakeLock.request('screen');
Enter fullscreen mode Exit fullscreen mode

However, the device can refuse a wake lock request if, for example, the battery of the device is low and discharging, or the user has turned on some kind of power conservation mode. The request will also be refused if the browser does not support the Wake Lock API so it's worthwhile considering what browser compatibility you are comfortable with. As the request can be refused, wrapping it within a try/catch block is recommended.

try {
  navigator.wakeLock.request('screen');
  console.log('Screen Wake Lock is active');
} catch (err) {
  console.error(err);
}
Enter fullscreen mode Exit fullscreen mode

There's nothing worse than a battery depleted device. It's therefore encouraged to either let the user manually turn off the wake lock, or to turn it off after a defined period. The W3C Editor's Draft also recommends ensuring that the user is aware that the wake lock is active on their device by displaying some form of unobtrusive notification.

In order to release the wake lock, we need to store the WakeLockSentinel object that is returned from the request and call the release method on it.

let wakeLock = null;

const requestWakeLock = async () => {
  try {
    wakeLock = await navigator.wakeLock.request('screen');
    console.log('Screen Wake Lock is active');
  } catch (err) {
    console.error(err);
  }
};

await requestWakeLock();

// Elsewhere, perhaps when a user clicks a button...
wakeLock.release();
wakeLock = null;
Enter fullscreen mode Exit fullscreen mode

Alternatively, the wake lock could be released after a defined period by using a timeout.

// Release wake lock after 10 minutes
window.setTimeout(() => {
  wakeLock.release();
  wakeLock = null;
}, 600000);
Enter fullscreen mode Exit fullscreen mode

Note that a screen wake lock will be automatically released when the user minimises the tab or window, or switches away from a tab or window where the screen wake lock is active.

If you are developing with React, you might want to try using my useWakeLock hook. Suggestions and contributions are welcome.

Further information on the Wake Lock API can be found in the W3C Editor's Draft and this web.dev article. If you have a cool use case for the screen wake lock API - share it with me in the comments below!

Thanks to Johannes Plenio for the cover photo from Unsplash.

Top comments (2)

Collapse
 
tomayac profile image
Thomas Steiner

By the way, we have landed native Screen Wake Lock support in NoSleep.js, so users of this library will automatically use the API if their browser supports it.

Collapse
 
tilakmaddy_68 profile image
Tilak Madichetti

Nice