IdleDetector
============

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
**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

IdleDetectorConstructor
-----------

`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
--------------

| Specification |
| --- |
| Idle Detection API # api-idledetector |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.