How to Use the Screen Wake Lock API in JavaScript

The Screen Wake Lock API provides web applications with the ability to prevent a device’s display from dimming, turning off, or locking while a web page is active. This article covers what the Screen Wake Lock API is, why it is important for modern web experiences, how to implement it using modern JavaScript, and how to handle lock lifecycles, visibility changes, and potential errors effectively.

What is the Screen Wake Lock API?

Modern operating systems aggressively save power by dimming and eventually turning off the screen when no touch, mouse, or keyboard input is detected. While this behavior extends battery life, it disrupts tasks that require passive viewing, such as reading a cooking recipe, presenting slides, scanning a digital boarding pass, or following turn-by-turn directions.

The Screen Wake Lock API solves this issue by exposing a standard interface via navigator.wakeLock. It allows client-side JavaScript to signal the operating system that the current web application requires the screen to remain illuminated.

How to Implement a Screen Wake Lock

To request a wake lock, use the asynchronous navigator.wakeLock.request() method with the 'screen' lock type.

1. Feature Detection

Before calling the API, always check if the browser supports it:

if ('wakeLock' in navigator) {
  console.log('Screen Wake Lock API is supported.');
} else {
  console.warn('Screen Wake Lock API is not supported in this browser.');
}

2. Requesting the Lock

To acquire a lock, create an asynchronous function that awaits navigator.wakeLock.request('screen').

let wakeLock = null;

async function requestWakeLock() {
  try {
    wakeLock = await navigator.wakeLock.request('screen');
    console.log('Wake Lock is active.');

    wakeLock.addEventListener('release', () => {
      console.log('Wake Lock was released.');
    });
  } catch (err) {
    console.error(`${err.name}, ${err.message}`);
  }
}

3. Releasing the Lock

When the task is complete, release the lock manually to conserve the user’s battery life:

function releaseWakeLock() {
  if (wakeLock !== null) {
    wakeLock.release()
      .then(() => {
        wakeLock = null;
      });
  }
}

Managing the Wake Lock Lifecycle

The browser automatically releases a wake lock in specific scenarios: - The user minimizes the window or switches to a different tab. - The device battery falls below a critical threshold. - The document’s visibility state changes to hidden.

Because wake locks are automatically released when the page loses visibility, applications must re-request the lock when the user returns.

document.addEventListener('visibilitychange', async () => {
  if (wakeLock !== null && document.visibilityState === 'visible') {
    await requestWakeLock();
  }
});

Security and Permission Requirements

The Screen Wake Lock API adheres to strict browser security policies: - Secure Contexts (HTTPS): The API is only accessible over HTTPS or localhost. - Page Visibility: A wake lock can only be acquired when the document is in the active, visible state. - System Overrides: The operating system may override the lock if the device battery is critically low or if the user manually locks the device screen.