Screen Wake Lock API: Prevent Screen Dimming

The Screen Wake Lock API allows web developers to prevent mobile devices from dimming their displays or locking the screen automatically during user interaction. Typically, mobile operating systems darken screens after brief periods of inactivity to preserve battery life, which disrupts use cases like following cooking recipes, reading sheet music, scanning barcodes, or watching non-video presentations. By implementing this API directly within client-side JavaScript, web applications can request continuous display illumination without requiring users to continuously touch the screen or install native applications.

How the API Works

The Screen Wake Lock API operates through the navigator.wakeLock interface by requesting a "sentinel" object. When active, this object signals the underlying operating system that the current web page requires the display to remain fully illuminated.

To request a wake lock, call the request() method:

let wakeLock = null;

async function requestWakeLock() {
  try {
    wakeLock = await navigator.wakeLock.request('screen');
    console.log('Screen Wake Lock is active.');
  } catch (err) {
    console.error(`${err.name}, ${err.message}`);
  }
}

Currently, the only supported lock type is 'screen', which specifically targets the display rather than background CPU execution.

Releasing the Lock

Keeping the screen awake consumes significant battery power. Therefore, applications must release the lock as soon as the interactive task concludes:

function releaseWakeLock() {
  if (wakeLock !== null) {
    wakeLock.release()
      .then(() => {
        wakeLock = null;
        console.log('Screen Wake Lock released.');
      });
  }
}

The lock also releases automatically under specific operating system conditions, such as low battery mode or when the user manually locks the device using the physical power button.

Handling Page Visibility Changes

A critical aspect of the Screen Wake Lock API is its automatic deactivation when a tab loses focus or becomes hidden. If a user switches tabs, minimizes the browser, or switches apps, the browser releases the lock to protect battery life.

To maintain the lock when the user returns to the page, developers must listen for the visibilitychange event and re-request the lock:

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

Security and Implementation Requirements

The Screen Wake Lock API requires a secure context (HTTPS) to function, preventing unauthorized or malicious scripts from silently draining device batteries. Additionally, browsers require feature detection before invocation:

if ('wakeLock' in navigator) {
  // Screen Wake Lock API is supported
  requestWakeLock();
} else {
  // Fallback behavior
}

By pairing permission checks with proper state management, interactive web applications provide an uninterrupted user experience identical to native mobile apps.