Package com.vaadin.flow.component.wakelock

Class WakeLock

java.lang.Object
com.vaadin.flow.component.wakelock.WakeLock
public final class WakeLock extends Object
Browser Screen Wake Lock API for Flow applications. Keeps the screen from dimming or locking while the lock is held ? useful for dashboards, kiosks, presentations, and recipe / workout screens.

Example: 

 WakeLock.request();

 Signal.effect(this, () -> {
     statusLabel.setText(
             WakeLock.activeSignal().get() ? "Screen will stay on" : "Idle");
 });

Lifecycle. request() fires the browser request asynchronously and activeSignal() flips to true once the browser confirms. The browser releases the lock automatically when the tab is hidden; the client transparently re-acquires it when the tab becomes visible again, so a single request() is enough for the lifetime of the view. Call release() to stop re-acquiring and drop the current lock.

Reliability caveats.

  • Safari only ships the Screen Wake Lock API from version 16.4.
  • The browser requires a secure context (HTTPS or localhost); on an insecure origin the call fails silently and activeSignal() stays false. Use availabilitySignal() to gate UI controls on this up front.
  • Some browsers release the lock on low battery or when the device enters power-saving mode; activeSignal() reflects this immediately.
Since:
25.2

  • Method Details

    • request

      public static void request()
      Asks the browser to acquire a screen wake lock for the current UI and keep re-acquiring it across tab visibility changes.

      The call is asynchronous and fire-and-forget: by the time this method returns the browser has not necessarily granted the lock yet. Observe activeSignal() to react to the actual state. Calling request() when a lock is already held is a no-op.

      Throws:
      IllegalStateException - if there is no current UI

    • request

      public static void request(UI ui)
      Asks the browser to acquire a screen wake lock for the given UI and keep re-acquiring it across tab visibility changes. Use this overload from background threads or anywhere UI.getCurrent() is unreliable.
      Parameters:
      ui - the UI to dispatch the request through, never null
      Throws:
      NullPointerException - if ui is null

    • request

      public static void request(SerializableConsumer<WakeLockError> onError)
      Asks the browser to acquire a screen wake lock for the current UI, with an error callback for persistent failures. Same lifecycle semantics as request(), but if the browser permanently refuses the request (feature unavailable, insecure context, NotAllowedError) the consumer is invoked on the UI thread with a WakeLockError describing the cause.

      The error callback fires only for persistent failures the application may want to surface ? typically by re-enabling a "Keep screen on" toggle and showing a message. It is not called when the lock is simply deferred (page hidden until the user returns to the tab) or when the browser temporarily releases the lock for power-management reasons; for those, observe activeSignal().

      Parameters:
      onError - consumer invoked on the UI thread when the request fails, never null
      Throws:
      NullPointerException - if onError is null
      IllegalStateException - if there is no current UI

    • request

      public static void request(SerializableConsumer<WakeLockError> onError, UI ui)
      Same as request(SerializableConsumer) on the given UI. Use this overload from background threads or anywhere UI.getCurrent() is unreliable.
      Parameters:
      onError - consumer invoked on the UI thread when the request fails, never null
      ui - the UI to dispatch the request through, never null
      Throws:
      NullPointerException - if either argument is null

    • release

      public static void release()
      Releases the screen wake lock on the current UI and stops re-acquiring it on subsequent visibility changes. Idempotent ? calling it when no lock is held is a no-op.
      Throws:
      IllegalStateException - if there is no current UI

    • release

      public static void release(UI ui)
      Releases the screen wake lock on the given UI and stops re-acquiring it on subsequent visibility changes. Use this overload from background threads or anywhere UI.getCurrent() is unreliable.
      Parameters:
      ui - the UI to dispatch the release through, never null
      Throws:
      NullPointerException - if ui is null

    • activeSignal

      public static Signal<Boolean> activeSignal()
      Returns a read-only signal that reflects whether the browser is currently holding the wake lock on behalf of the current UI.

      Starts as false, flips to true when the browser confirms a request, and flips back to false whenever the browser releases the lock ? explicitly through release(), automatically when the tab becomes hidden, or because the browser dropped it (power saving, low battery). When the tab is shown again the client re-requests the lock if release() has not been called, so the signal flips back to true shortly after.

      Use Signal.effect(owner, ...) to react to changes and .peek() for a snapshot outside a reactive context.

      Returns:
      the read-only active-state signal
      Throws:
      IllegalStateException - if there is no current UI

    • activeSignal

      public static Signal<Boolean> activeSignal(UI ui)
      Returns the read-only active-state signal for the given UI. Same semantics as activeSignal(); use this overload from background threads or anywhere UI.getCurrent() is unreliable.
      Parameters:
      ui - the UI to read the signal from, never null
      Returns:
      the read-only active-state signal
      Throws:
      NullPointerException - if ui is null

    • availabilitySignal

      public static Signal<WakeLockAvailability> availabilitySignal()
      Returns a read-only signal hinting at whether the Screen Wake Lock API is usable in the current UI's page context. Useful for hiding a "keep screen on" toggle entirely on insecure origins or browsers that do not implement the API.

      The value is seeded during bootstrap; the brief window between UI attach and bootstrap completion surfaces as WakeLockAvailability.UNKNOWN.

      Returns:
      the availability hint signal
      Throws:
      IllegalStateException - if there is no current UI

    • availabilitySignal

      public static Signal<WakeLockAvailability> availabilitySignal(UI ui)
      Returns the availability hint signal for the given UI. Same semantics as availabilitySignal(); use this overload from background threads or anywhere UI.getCurrent() is unreliable.
      Parameters:
      ui - the UI to read the signal from, never null
      Returns:
      the availability hint signal
      Throws:
      NullPointerException - if ui is null