Screen Wake Lock API: a practical guide with error handling

Versions as of 26 September 2026. Support claims come from browser documentation and engine source; real-device results appear in the wake lock browser support matrix once recorded, with platforms, notes and sources for each row.

Call request('screen') from a visible page served over HTTPS. Keep the object it returns: it is your only proof that the lock is held, and its release event tells you when it is gone. The wakeLock property only exists in secure contexts, so check with 'wakeLock' in navigator rather than calling and catching: calling request on undefined throws a TypeError that looks like a bug in your code. https:// pages and http://localhost count as secure.

let sentinel = null;let wanted = false; async function keepScreenOn() {  wanted = true;  if (!('wakeLock' in navigator)) return 'unsupported';  try {    const s = await navigator.wakeLock.request('screen');    s.addEventListener('release', () => {      if (sentinel === s) sentinel = null;    });    sentinel = s;    return 'held';  } catch (err) {    // NotAllowedError: page hidden, Permissions-Policy,    // no tap yet in Safari, or Firefox at 5% battery or less    console.warn(`${err.name}: ${err.message}`);    return 'refused';  }} startButton.addEventListener('click', keepScreenOn);

Start the request from a click handler: that click is the tap Safari needs. The wanted flag separates "the user asked for the screen to stay on" from "the browser currently holds a lock". The browser can drop the second at any time; only the user should change the first. @awaketab/wake wraps this pattern, with a gesture-aware video fallback and a change event every time the state moves. Its source is MIT on GitHub, and the npm package is coming soon; the @awaketab/wake library page runs a live demo.

The browser rejects the promise with NotAllowedError for a small set of reasons. Battery saver modes are not one of them in Chromium or Safari. Here is what each cause looks like and what AwakeTab shows.

Checked against engine source on 26 September 2026.

Sources: Chromium wake_lock.cc, WebKit WakeLock.cpp and Firefox WakeLockJS.cpp.

The battery-saver row matters because many pages, including earlier versions of ours, blamed battery savers for NotAllowedError. The engines don't check for them. A saver can still change how long the device waits before the display goes dark, but that happens in the operating system's settings, outside the browser, and your promise never rejects because of it.

Switching tabs or apps, minimising the window or locking the phone hides the document. A visible window that has lost focus keeps its lock. The sentinel fires release, and your page should show that honestly instead of a running timer. The same event fires when you call release() yourself and when the browser takes the lock back for its own reasons.

document.addEventListener('visibilitychange', () => {  if (wanted && !sentinel && document.visibilityState === 'visible') {    keepScreenOn();  }});

Safari usually accepts that second request thanks to the earlier tap; if it rejects, show a button so the next tap can ask.

Each box is one of AwakeTab's pill messages. The dashed line is the step most pages forget: asking again when the tab comes back.

Only if the parent page allows it. The screen-wake-lock feature is allowed for the page's own origin by default; a cross-origin iframe needs the embedding page to delegate it with allow="screen-wake-lock". Without it, the Permissions-Policy blocks the request and it fails with NotAllowedError, which is why "iframe without allow" is the first thing to check when a widget works on its own and fails when embedded.

<iframe src="https://widget.example.com/timer" allow="screen-wake-lock"></iframe>

A site can also switch the feature off, or allow named origins, with a response header. screen-wake-lock=() blocks it everywhere on that page, including in the top-level document.

Permissions-Policy: screen-wake-lock=(self "https://widget.example.com")

When the user stops or the time is up, release the lock and clear the flag that says they wanted it. Otherwise your visibilitychange handler will ask again the next time the tab is shown.

async function letScreenSleep() {  wanted = false;  const s = sentinel;  sentinel = null;  await s?.release();} stopButton.addEventListener('click', letScreenSleep);

Before the API, libraries kept screens on by playing a tiny silent video in a loop. It still works as a fallback for browsers without the API, with three costs. It needs a user gesture, because browsers block video autoplay until someone interacts. It uses more power than a native lock, since the media pipeline stays busy. And your code can't easily tell whether it is working, only whether play() resolved. Use it only when wakeLock is missing, never as a second attempt after a NotAllowedError. NoSleep.js vs @awaketab/wake compares two libraries that handle this differently.

It keeps the display on while the page is visible. It can't hold from a hidden tab, stop a laptop sleeping when the lid closes, or change an operating system rule such as a work sign-in lock. It sends no input, so it doesn't change a chat app's Away timer. On desktop Chrome or Edge, an extension with the power permission, such as AwakeTab for Chrome, can keep the screen on from a hidden tab; a web page can't.