W3cubDocs

/Web APIs

IdleDetector

Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The IdleDetector interface of the Idle Detection API provides methods and events for detecting user activity on a device or screen.

This interface requires a secure context.

EventTarget IdleDetector

Constructor

IdleDetector() Experimental

Creates a new IdleDetector object.

Instance properties

IdleDetector.userState Read only Experimental

Returns a string indicating whether the users has interacted with either the screen or the device within the threshold provided to start(), one of "active" or "idle". This attribute returns null before start() is called.

IdleDetector.screenState Read only Experimental

Returns a string indicating whether the screen is locked, one of "locked" or "unlocked". This attribute returns null before start() is called.

Events

change Experimental

Called when the value of userState or screenState has changed.

Static methods

IdleDetector.requestPermission() Experimental

Returns a Promise that resolves when the user has chosen whether to grant the origin access to their idle state. Resolves with "granted" on acceptance and "denied" on refusal.

Instance methods

IdleDetector.start() Experimental

Returns a Promise that resolves when the detector starts listening for changes in the user's idle state. userState and screenState are given initial values. This method takes an optional options object with the threshold in milliseconds where inactivity should be reported and signal for an AbortSignal to abort the idle detector.

Examples

The following example shows creating a detector and logging changes to the user's idle state. A button is used to get the necessary user activation before requesting permission.

js

const controller = new AbortController();
const signal = controller.signal;

startButton.addEventListener("click", async () => {
  if ((await IdleDetector.requestPermission()) !== "granted") {
    console.error("Idle detection permission denied.");
    return;
  }

  try {
    const idleDetector = new IdleDetector();
    idleDetector.addEventListener("change", () => {
      const userState = idleDetector.userState;
      const screenState = idleDetector.screenState;
      console.log(`Idle change: ${userState}, ${screenState}.`);
    });

    await idleDetector.start({
      threshold: 60_000,
      signal,
    });
    console.log("IdleDetector is active.");
  } catch (err) {
    // Deal with initialization errors like permission denied,
    // running outside of top-level frame, etc.
    console.error(err.name, err.message);
  }
});

stopButton.addEventListener("click", () => {
  controller.abort();
  console.log("IdleDetector is stopped.");
});

Specifications

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
IdleDetector 94 11494–96 No No 80 No 94 94 No 66 No 17.0
IdleDetector 94 11494–96 No No 80 No 94 94 No 66 No 17.0
change_event 94 11494–96 No No 80 No 94 94 No 66 No 17.0
requestPermission_static 94 11494–96 No No 80 No 94 94 No 66 No 17.0
screenState 94 11494–96 No No 80 No 94 94 No 66 No 17.0
start 94 11494–96 No No 80 No 94 94 No 66 No 17.0
userState 94 11494–96 No No 80 No 94 94 No 66 No 17.0

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/IdleDetector