on how to integrate the into any React application with automatic reacquisition of a lock using . TLDR: LIVE demo 🚀 Screen Wake Lock API react-use-wake-lock Historically, browsers didn't support any APIs to control sleep settings. Devices usually turn off displays after some time to improve power usage, improve security, and prolong the life of hardware in general. However, this behavior does not always provide the best UX for users. In some cases, browsers are smart enough to prevent sleep by using heuristics like playing video. Some libraries utilize this to hack solutions for this problem (e.g., ). However, this comes with an extra penalty hit on performance and battery. NoSleep.js Modern browsers now support an official API to manage this process. This provides more reliable control over the sleep functionality. In certain scenarios, it's perfectly reasonable to prevent the device from locking (for instance, in systems like navigation, photo galleries, calling, etc.), which significantly enhances the overall user experience. Although this API is not fully standardized and is still in the stage, it has extensive browser support. This is particularly noteworthy since it is now also supported by Safari version 16.4 and above (including mobile Safari). As such, this API is currently . Working Draft supported by the majority of major browsers Let's take a closer look at how to use it in practice and what are its limitations. Screen Wake Lock API There are 3 important limitations when you are allowed to use this API: Your app should be in an active tab. Your app should be served from the . Secure Context Using this feature is not blocked by the Permissions Policy The API itself is quite straightforward and involves two steps: requesting a lock and releasing it. Being Promise-based, you need to wait for the promise to resolve in order to acquire the lock. There are two main parts in the API: - Interface that can be used to request the lock from the browser. WakeLock - Interface to the underlying lock that can be used to release the lock WakeLockSentinel So, let's connect all the pieces together. Requesting a Lock To request a lock, we need to use and invoke method. You need to provide the type of lock, but only type is supported at this moment. navigator.wakelock request() screen const requestScreenWakeLock = async () => {
  // Check if wakelock API is available
  if (!("wakeLock" in navigator)) {
    console.error("Screen Wake Lock API is not supported by the browser");
    return;
  }

  try {
    const wakeLock = await navigator.wakeLock.request("screen");
  } catch (err) {
    // There are various reason why lock might not be acquired such as tab is not active, low battery on a device, permissions
    console.error(`WakeLock request error: ${err.message}`);
  }
}; It's important to note that the browser might reject the request for several reasons, such as low battery level or page visibility, among others. Therefore, it's crucial to ensure that the Promise has been resolved to ensure success. Releasing a Lock Once you have a from API,  you can use it to release a lock. For this, you can simply call method on it and wait for the to resolve. You can also check the status of a lock in a property and . WakeLockSentinel request() release() Promise released type The simplest snippet: try {
  console.log('Released state before: 'wakeLock.released); // false

  await wakeLock.release();

  console.log('Released state after: 'wakeLock.released); // true
} catch (err) {
  console.error(`WakeLock release error: ${err.message}`);
} It's important to note that the browser might decide to release the lock even without a specific request from you. Therefore, to keep the state of the app in sync with the lock status, it's crucial to listen for the wake lock release event. wakeLock.addEventListener("release", () => {
  // the wake lock has been released
  console.log('Wake Lock has been released');
}); While the API itself appears quite straightforward, there are some nuances to consider when implementing it. For instance, since the lock will be auto-released when the browser is no longer active, you'll need to manage this aspect yourself. This involves listening for visibility changes in order to reacquire the lock. For pure JS implementation, you can check the and . MDN example source code However, in order to integrate it into a React-based app, it would be much easier to have a wrapper that provides a hook-based API to work with Screen Wake Lock API. Using Screen Wake Lock API in React I have wrapped this API into a React hook to make it much easier to use in any React application. The library offers a simple way to hide the complexities of handling the async nature of Screen Wake Lock API as well as automatically incorporate automatic reacquisition of a lock in case the app loses visibility (becomes inactive). react-use-wake-lock Additionally, it also supports TypeScript and has 100% test-coverage. Let's take a look at the simplest example. First, you need to install this library by running (or / depending on your preference) npm install react-use-wake-lock --save pnpm yarn Then, just add it to your React files as shown in a minimal example below import useWakeLock from "react-use-wake-lock";

function MinimalExampleComponent() {
  const { isSupported, isLocked, request, release } = useWakeLock();

  // isSupported: boolean - checks feature is supported by the browser
  // isLocked: boolean    - checks lock is currently active
  // request: () => void  - request lock, once successfully acquired isLocked will change to TRUE
  // release: () => void  - release the lock, once successfully released isLocked will change to FALSE

  return (
    <div>
      <h3>Screen Wake Lock API supported: {isSupported ? "Yes" : "No"}</h3>
      <h3>Locked: {`${isLocked ? "Yes" : "No"}`}</h3>
      <button type="button" onClick={() => (isLocked ? release() : request())}>
        {isLocked ? "Release" : "Request"}
      </button>
    </div>
  );
} This is just a . However, the library offers more control and error handling by specifying extra options to the hook. Feel free to check the or . minimal example full example code official documentation You can check this example or check the . minimal demo full example with support for events and error handling End-to-end demo on iOS (Safari) Conclusion Leveraging modern browser APIs is a powerful strategy that allows us to construct a superior user experience, effectively bridging the gap between web and native applications by bringing an app-like feel to the web. This article serves as a hands-on guide detailing how to utilize the modern Screen Wake Lock API within any application built on React. You can find the complete source code as well as demo and installation instructions for this example on GitHub . https://github.com/dlitsman/react-use-wake-lock

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

How to Use Screen Wake Lock API in React to Manage Screen Locking/Dimming in a Browser

Too Long; Didn't Read

Dmitrii Litsman

STORY’S CREDIBILITY

Guide

Share Your Thoughts

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...