Stay awake with the Screen Wake Lock API

The Screen Wake Lock API provides a way to prevent devices from dimming or locking the screen when an application needs to keep running.

Dec 18, 2018
• Updated Apr 14, 2020

What is the Screen Wake Lock API? #

To avoid draining the battery, most devices quickly go to sleep when left
idle. While this is fine most of the time, some applications need to keep the
screen awake to complete their work. Examples include cooking apps
that show the steps of a recipe or a game
like Ball Puzzle, which uses the device
motion APIs for input.

The Screen Wake Lock API provides a way to prevent the device from dimming
and locking the screen. This
capability enables new experiences that, until now, required a native app.

The Screen Wake Lock API reduces the need for hacky and potentially
power-hungry workarounds. It addresses the shortcomings of an older API
that was limited to simply keeping the screen on and had a number of
security and privacy issues.

Suggested use cases for the Screen Wake Lock API #

RioRun,
a web app developed by The Guardian,
was a perfect use case (though it’s no longer available).
The app takes you on a virtual audio tour of Rio, following the route of the 2016
Olympic marathon.
Without wake locks, users’ screens would turn off frequently while the tour played,
making it hard to use.

Of course, there are plenty of other use cases:

• A recipe app that keeps the screen on while you bake a cake or cook
  dinner
• A boarding pass or ticket app that keeps the screen
  on until the barcode has been scanned
• A kiosk-style app that keeps the screen on continuously
• A web-based presentation app that keeps the screen
  on during a presentation

Current status #

Using the Screen Wake Lock API #

Enabling support during the origin trial phase #

The Screen Wake Lock API is available as an origin trial in Chrome 79.
The origin trial is expected to end in Chrome 83
and the feature to launch in Chrome 84.

Origin trials allow you to try new features and give feedback on their
usability, practicality, and effectiveness to the web standards community. For
more information, see the Origin Trials Guide for Web Developers.
To sign up for this or another origin trial, visit the registration page.

Register for the origin trial #

1. Request a token for your origin.
2. Add the token to your pages. There are two ways to do that:
   • Add an origin-trial <meta> tag to the head of each page. For example,
     this may look something like:
     <meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
   • If you can configure your server, you can also add the token
     using an Origin-Trial HTTP header. The resulting response header should
     look something like:
     Origin-Trial: TOKEN_GOES_HERE

Enabling via chrome://flags #

To experiment with the Screen Wake Lock API locally, without an origin trial token,
enable the #experimental-web-platform-features flag in chrome://flags.

Demo #

Check out the Screen Wake Lock demo and demo source.
Notice how the screen wake lock gets automatically released when you switch tabs
or switch to a different app.

Wake lock types #

The Screen Wake Lock API currently provides just one type of wake lock: screen.

screen wake lock #

A screen wake lock prevents the device’s screen from turning
off so that the user can see the information that’s displayed on screen.

Getting a screen wake lock #

To request a screen wake lock, you need to call the navigator.wakeLock.request() method
that returns a WakeLockSentinel object.
You pass this method the desired wake lock type as a parameter,
which currently is limited to just 'screen'.
The browser can refuse the request for various reasons (for example,
because the battery charge level is too low),
so it’s a good practice to wrap the call in a try…catch statement.
The exception’s message will contain more details in case of failure.

Releasing a screen wake lock #

You also need a way to release the screen wake lock, which is achieved by calling the
release() method of the WakeLockSentinel object.
If you don’t store a reference to the WakeLockSentinel, there’s no way
to release the lock manually, but it will be released once the current tab is invisible.

If you want to automatically release the screen wake lock
after a certain period of time has passed,
you can use window.setTimeout() to call release(), as shown in the example below.

let wakeLock = null;

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

await requestWakeLock();
window.setTimeout(() => {
wakeLock.release();
wakeLock = null;
}, 5000);

The screen wake lock lifecycle #

When you play with the screen wake lock demo, you’ll notice that screen wake locks
are sensitive to page visibility and
full-screen mode. This means that the screen wake lock
will automatically be released when you enter full-screen mode, minimize a
tab or window, or switch away from a tab or window where a screen wake lock is active.

To reacquire the screen wake lock,
listen for the visibilitychange event and
the fullscreenchange event
and request a new screen wake lock when they occur:

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

Minimize your impact on system resources #

Should you use a screen wake lock in your app?
The approach you take depends on the needs of your app. Regardless, you should
use the most lightweight approach possible for your app to minimize its
impact on system resources.

Before adding a screen wake lock to your app, consider whether your use cases could
be solved with one of the following alternative solutions:

• If your app is performing long-running downloads, consider using
  background fetch.
• If your app is synchronizing data from an external server, consider using
  background sync.

Feedback #

The Web Platform Incubator Community Group (WICG)
and the Chrome team want to hear about your
thoughts and experiences with the Screen Wake Lock API.

Tell us about the API design #

Is there something about the API that doesn’t work as expected? Or
are there missing methods or properties that you need to implement your idea?

Report a problem with the implementation #

Did you find a bug with Chrome’s implementation? Or is the implementation
different from the spec?

• File a bug at https://new.crbug.com. Be sure to include as much
  detail as you can, provide simple instructions for reproducing the bug, and
  set Components to Blink>WakeLock. Glitch works great
  for sharing quick and easy repros.

Show support for the API #

Are you planning to use the Screen Wake Lock API? Your public support helps the
Chrome team prioritize features and shows other browser vendors how
critical it is to support them.

Helpful links #

Acknowledgements #

Hero image by
Kate Stone Matheson on Unsplash.