API in Capabilities
Idle Detection API
Published Updated
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).
Syntax
Section titled “Syntax”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.
Parameters
Section titled “Parameters”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().
Exceptions
Section titled “Exceptions”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.
Examples
Section titled “Examples”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.
See also
Section titled “See also”- Screen Wake Lock API, the complementary request to keep the screen from locking
- Web Locks API, for coordinating work between tabs once a user goes idle
- PWAs on Firefox
- Idle Detection API: start() method (wicg.github.io)
- Idle Detection API: requestPermission() method (wicg.github.io)
- IdleDetector browser compatibility (developer.mozilla.org)
Specifications
| Specification | Status |
|---|---|
| Idle Detection API | WICG draft |
| Idle Detection API: IdleDetector interface | WICG draft |
| Idle Detection API: start() method | WICG draft |
| Idle Detection API: requestPermission() method | WICG draft |
- Legend
- Yes
- Partial
- Flag
- No
- Unknown
| Browser / Platform | Support | Versions | Confidence | Source | Notes |
|---|---|---|---|---|---|
| Chrome (Desktop)# | Yes | 94 | high | source | — |
| Chrome (Android)# | Yes | 94 | high | source | 1 |
| Edge (Desktop)# | Yes | 114 | high | source | — |
| Firefox (Desktop)# | No | — | high | source | 2 |
| Firefox (Android)# | No | — | high | source | 34 |
| Safari (macOS)# | No | — | high | source | 5 |
| Safari (iOS)# | No | — | high | source | 67 |
| Samsung Internet# | Yes | 17.0 | high | source | 8 |
| WebView (Android)# | Yes | 94 | high | source | 9 |
- Derived by browser-compat-data mirroring from Chrome.
- No Firefox support is recorded in browser-compat-data.
- No Firefox for Android support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Firefox.
- No Safari support is recorded in browser-compat-data.
- No Safari on iOS support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Safari.
- Derived by browser-compat-data mirroring from Chrome Android.
- Derived by browser-compat-data mirroring from Chrome Android.