Idle Detection API

Idle Detection API is a browser API that tells a web page when the user has stopped interacting with their device or when the screen is locked. It is exposed as the IdleDetector class in secure contexts and is a Web Platform Incubator Community Group draft. The spec's motivating case is sending notifications to the device a person is actually using, and the shortest threshold you can ask for is 60,000 milliseconds.

How it works

IdleDetector reports two separate states. userState is "active" or "idle", and it describes input such as keyboard, mouse or touch in the last threshold milliseconds. screenState is "locked" or "unlocked", and it reports whether a screensaver or lock screen hides the content. Both are null until detection has started.

The flow has three steps:

• Call IdleDetector.requestPermission() from a user gesture. It resolves to a PermissionState, and the permission name is "idle-detection".
• Create new IdleDetector() and add a change listener.
• Call detector.start({ threshold, signal }). The threshold is in milliseconds, and an AbortSignal stops the detector.

If the threshold is less than 60,000, start() returns a promise rejected with a TypeError. The spec explains that the floor of 60 seconds exists to limit how finely a site can infer typing behavior, and the permission prompt guards against profiling when and how long a user is active. The class is exposed in windows and dedicated workers, but requestPermission() is window-only.

The permission policy has the same name, and its default allowlist is 'self'. A site can switch it off entirely with the response header Permissions-Policy: idle-detection 'none'. The sample reproduces the threshold rule, since Node has no IdleDetector.

const MIN = 60000;
function start(threshold) {
  if (threshold < MIN) return "TypeError: threshold " + threshold + " is below " + MIN;
  return "ok: idle after " + threshold / 1000 + " s without input";
}
console.log(start(500));
console.log(start(59999));
console.log(start(60000));
console.log(start(5 * 60 * 1000));

Output:

TypeError: threshold 500 is below 60000
TypeError: threshold 59999 is below 60000
ok: idle after 60 s without input
ok: idle after 300 s without input

What is the minimum idle threshold?

The minimum threshold is 60,000 milliseconds, which is 60 seconds. Any smaller value makes start() reject with a TypeError, so there is no way to detect a two-second pause. Pick a value that matches your product, such as 300,000 for five minutes.

Which browsers support Idle Detection?

MDN compatibility data lists IdleDetector in Chrome 94 and Opera 80, and in Edge 114, with no support in Firefox or Safari. The API is flagged as experimental. Feature-detect with "IdleDetector" in window and fall back to timers on input events.

Common pitfalls

• Relying on page events alone: visibility and mouse events cannot tell a user at a coffee break from one working in a window beside yours, which is the gap this API fills. Do not use IdleDetector as proof the person left.
• Using a short threshold: values under 60,000 reject with a TypeError, so a "5 second idle" feature is not possible here.
• Requesting permission on load: requestPermission() without transient activation rejects with NotAllowedError, and a denied permission makes start() reject with NotAllowedError too.
• Starting a detector twice: start() on a detector that is not stopped rejects with InvalidStateError. Create a new IdleDetector instead.
• Ignoring screenState: a locked screen can be reported separately from "idle", so handle both fields in the change handler.
• Blocking it by accident: a Permissions-Policy of idle-detection 'none' disables the feature even on your own pages.

Related terms

• Permissions-Policy header — controls the idle-detection feature
• HTTPS — the secure context the API requires
• Notifications API — another permission-gated API that depends on user engagement
• Geolocation API — a similar prompt-based permission model
• Promise — requestPermission() and start() both return one

See also

• Term: Permissions-Policy header — how to allow or block the idle-detection feature