The Screen Wake Lock API
Tags: webdev, javascript, wakelock, pwa
Published: 2020-07-23 04:27:38

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](https://github.com/richtr/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](https://9to5google.com/2020/07/13/google-and-microsoft-pwa/). 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.

```jsx
navigator.wakeLock.request('screen');
```

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](https://developer.mozilla.org/en-US/docs/Web/API/WakeLock/request#Browser_compatibility) you are comfortable with. As the request can be refused, wrapping it within a try/catch block is recommended.

```jsx
try {
  navigator.wakeLock.request('screen');
  console.log('Screen Wake Lock is active');
} catch (err) {
  console.error(err);
}
```

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](https://w3c.github.io/screen-wake-lock/) 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. 

```jsx
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;
```

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

```jsx
// Release wake lock after 10 minutes
window.setTimeout(() => {
  wakeLock.release();
  wakeLock = null;
}, 600000);
```

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](https://www.npmjs.com/package/use-wake-lock). Suggestions and contributions are welcome.

Further information on the Wake Lock API can be found in the [W3C Editor's Draft](https://w3c.github.io/screen-wake-lock/) and this [web.dev article](https://web.dev/wakelock/). 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](https://unsplash.com/photos/fmTde1Fe23A).