Skip to content

API in Capabilities

Idle Detection API

Published Updated

Limited availabilityNot supported in Firefox (Desktop), Firefox (Android), Safari (macOS), Safari (iOS)WICG draft

IdleDetector tells a page whether the user has interacted with the device within a threshold you choose (at least one minute) and whether the screen is locked. It fires a change event when either state changes. It is a WICG draft gated by the idle-detection permission, meant for presence indicators in chat apps and for pausing expensive work when nobody is watching.

Support is Chromium only: Chrome 94 on desktop and Android, Edge 94 to 96 and again from Edge 114 (the interface was absent in between), Opera and Samsung Internet in the matching Chromium releases. Firefox and Safari have no implementation in any version (BCD api.IdleDetector).

new IdleDetector()
IdleDetector.requestPermission()
idleDetector.start()
idleDetector.start(options)

The constructor takes no arguments. requestPermission() is a static method, [Exposed=Window] only, that returns a Promise<PermissionState> resolving to "granted", "denied", or "prompt". start() returns a Promise<undefined> that resolves once the detector is "started". The whole interface is [SecureContext] and is also exposed in dedicated workers, where start() works but requestPermission() does not exist.

start() takes one optional options argument, an IdleOptions dictionary.

Member Type Required Description
threshold unsigned long long ([EnforceRange]) No Milliseconds of inactivity after which userState becomes "idle". The minimum is 60,000; smaller values reject the promise. Negative or non-finite values throw a TypeError at the binding layer because of [EnforceRange].
signal AbortSignal No Aborting the signal stops the detector and rejects the pending start() promise with the signal’s abort reason.

After start() resolves, two read-only attributes carry the state: userState is "active" or "idle", and screenState is "locked" or "unlocked". Both are null until the first start() has completed, so read them inside the change handler or after await idleDetector.start(), not synchronously after new IdleDetector().

The specification defines the following rejections.

Method Exception Condition
requestPermission() InvalidStateError The document is not fully active.
requestPermission() NotAllowedError The call has no transient user activation; the prompt can only follow a click or key press.
start() InvalidStateError The document is not fully active, or the detector’s internal state is not "stopped" (it is already starting or started).
start() NotAllowedError The document is not allowed to use the idle-detection policy-controlled feature (default allowlist 'self'), or the idle-detection permission state is "denied" when the detector is started.
start() TypeError threshold is below 60,000 ms.
start() the signal’s abort reason options.signal is already aborted when start() is called, or is aborted while the promise is pending.

Chromium departs from the specification in one place: when Permissions Policy blocks the feature, start() rejects with a SecurityError rather than a NotAllowedError (see the callout below). Chromium also rejects start() with NotSupportedError and the message Idle detection not available. when the browser-side monitor disconnects while the start() promise is still pending, a case the specification does not model.

Check for the constructor first and fall back to the page’s own activity signals (visibilitychange, input events) in Firefox and Safari, where IdleDetector is undefined.

Showing an “away” presence badge after one minute of inactivity

Section titled “Showing an “away” presence badge after one minute of inactivity”

The permission request runs inside the click handler, which supplies the transient activation that requestPermission() requires. When the API is missing, the fallback marks the user away whenever the tab is hidden, which is the only signal those browsers give you.

const badge = document.querySelector('#presence');
const enable = document.querySelector('#enable-presence');
function markAway(isAway) {
badge.textContent = isAway ? 'Away' : 'Active';
}
async function startPresence() {
if (!('IdleDetector' in window)) {
document.addEventListener('visibilitychange', () => {
markAway(document.visibilityState === 'hidden');
});
return 'fallback';
}
const state = await IdleDetector.requestPermission();
if (state !== 'granted') return 'denied';
const detector = new IdleDetector();
const syncBadge = () => {
markAway(detector.userState === 'idle' || detector.screenState === 'locked');
};
detector.addEventListener('change', syncBadge);
await detector.start({ threshold: 60_000 });
syncBadge();
return 'started';
}
enable.addEventListener('click', async () => {
try {
enable.hidden = (await startPresence()) !== 'denied';
} catch (err) {
console.error(`${err.name}: ${err.message}`);
}
});

'denied' keeps the button visible so the user can retry after changing the site setting; a second requestPermission() resolves with the stored decision without a new prompt.

Stopping the detector with an AbortSignal when the user signs out

Section titled “Stopping the detector with an AbortSignal when the user signs out”

There is no stop() method. The only way to end monitoring is the AbortSignal passed to start(), which also releases the browser-side monitor. Aborting after start() resolved rejects nothing; aborting while start() is pending rejects that promise with the abort reason, so catch distinguishes a deliberate abort from a real failure.

const controller = new AbortController();
async function watchUntilSignOut(detector) {
try {
await detector.start({ threshold: 120_000, signal: controller.signal });
} catch (err) {
if (err.name === 'AbortError') return; // signed out before start() settled
throw err;
}
}
document.querySelector('#sign-out').addEventListener('click', () => {
controller.abort();
});

After controller.abort() the detector returns to the "stopped" state and the same instance may be started again with a fresh signal; the old userState and screenState values are no longer updated.

Specifications

SpecificationStatus
Idle Detection APIWICG draft
Idle Detection API: IdleDetector interfaceWICG draft
Idle Detection API: start() methodWICG draft
Idle Detection API: requestPermission() methodWICG draft
  • Legend
  • Yes
  • Partial
  • Flag
  • No
  • Unknown
Browser / PlatformSupportVersionsConfidenceSourceNotes
Chrome (Desktop)#Yes94highsource—
Chrome (Android)#Yes94highsource1
Edge (Desktop)#Yes114highsource—
Firefox (Desktop)#No—highsource2
Firefox (Android)#No—highsource34
Safari (macOS)#No—highsource5
Safari (iOS)#No—highsource67
Samsung Internet#Yes17.0highsource8
WebView (Android)#Yes94highsource9
  1. Derived by browser-compat-data mirroring from Chrome.
  2. No Firefox support is recorded in browser-compat-data.
  3. No Firefox for Android support is recorded in browser-compat-data.
  4. Derived by browser-compat-data mirroring from Firefox.
  5. No Safari support is recorded in browser-compat-data.
  6. No Safari on iOS support is recorded in browser-compat-data.
  7. Derived by browser-compat-data mirroring from Safari.
  8. Derived by browser-compat-data mirroring from Chrome Android.
  9. Derived by browser-compat-data mirroring from Chrome Android.

Source data: /compatibility/idle-detection.json · Global usage: 75 % (StatCounter 2026-09, CC BY-SA 4.0)

Source: spec · MDN · Last verified 2026-10-03 · Confidence: high (computed from sources)