useIdleDetectionApi

About

Hook to detect when user is idle using the native Idle Detection API with polyfill fallback. This hook provides comprehensive idle detection capabilities including user activity state, screen lock state, and permission management.

Examples

Basic idle detection

import { useIdleDetectionApi } from "rooks";

export default function App() {
  const { isIdle, userState, screenState, isSupported, start, stop } = useIdleDetectionApi({
    threshold: 60000, // 60 seconds
    autoStart: true,
    requestPermission: true
  });

  return (
    <div>
      <h3>Idle Detection Status</h3>
      <p>API Supported: {isSupported ? "Yes" : "No"}</p>
      <p>User State: <strong>{userState}</strong></p>
      <p>Screen State: <strong>{screenState}</strong></p>
      <p>Is Idle: <strong>{isIdle ? "Yes" : "No"}</strong></p>
      
      <button onClick={start}>Start Detection</button>
      <button onClick={stop}>Stop Detection</button>
    </div>
  );
}

With state change callbacks

import { useIdleDetectionApi } from "rooks";
import { useState } from "react";

export default function App() {
  const [lastChange, setLastChange] = useState(null);
  const [errors, setErrors] = useState([]);

  const { isIdle, userState, screenState, isPermissionGranted } = useIdleDetectionApi({
    threshold: 120000, // 2 minutes
    autoStart: true,
    requestPermission: true,
    onIdleChange: (state) => {
      setLastChange({
        timestamp: new Date().toLocaleTimeString(),
        ...state
      });
    },
    onError: (error) => {
      setErrors(prev => [...prev, error.message]);
    }
  });

  return (
    <div>
      <h3>Idle Detection with Callbacks</h3>
      <p>Current State: {isIdle ? "Idle" : "Active"}</p>
      <p>User State: {userState}</p>
      <p>Screen State: {screenState}</p>
      <p>Permission Granted: {isPermissionGranted ? "Yes" : "No"}</p>
      
      {lastChange && (
        <div>
          <h4>Last Change:</h4>
          <p>Time: {lastChange.timestamp}</p>
          <p>Was Idle: {lastChange.isIdle ? "Yes" : "No"}</p>
          <p>User State: {lastChange.userState}</p>
          <p>Screen State: {lastChange.screenState}</p>
        </div>
      )}
      
      {errors.length > 0 && (
        <div>
          <h4>Errors:</h4>
          {errors.map((error, index) => (
            <p key={index} style={{ color: "red" }}>{error}</p>
          ))}
        </div>
      )}
    </div>
  );
}

Manual control with custom threshold

import { useIdleDetectionApi } from "rooks";
import { useState } from "react";

export default function App() {
  const [customThreshold, setCustomThreshold] = useState(60000);
  const [isStarted, setIsStarted] = useState(false);

  const { 
    isIdle, 
    userState, 
    screenState, 
    isSupported, 
    isPermissionGranted, 
    start, 
    stop 
  } = useIdleDetectionApi({
    threshold: customThreshold,
    autoStart: false, // Manual control
    requestPermission: true
  });

  const handleStart = async () => {
    await start();
    setIsStarted(true);
  };

  const handleStop = () => {
    stop();
    setIsStarted(false);
  };

  const handleThresholdChange = (e) => {
    setCustomThreshold(parseInt(e.target.value) * 1000);
  };

  return (
    <div>
      <h3>Manual Idle Detection Control</h3>
      
      <div>
        <label>
          Threshold (seconds): 
          <input 
            type="number" 
            min="60" 
            value={customThreshold / 1000} 
            onChange={handleThresholdChange}
            disabled={isStarted}
          />
        </label>
      </div>
      
      <div>
        <button onClick={handleStart} disabled={isStarted || !isSupported}>
          Start Detection
        </button>
        <button onClick={handleStop} disabled={!isStarted}>
          Stop Detection
        </button>
      </div>
      
      <div>
        <h4>Status:</h4>
        <p>API Supported: {isSupported ? "Yes" : "No"}</p>
        <p>Permission Granted: {isPermissionGranted ? "Yes" : "No"}</p>
        <p>Detection Active: {isStarted ? "Yes" : "No"}</p>
        <p>Current State: {isIdle ? "Idle" : "Active"}</p>
        <p>User State: {userState}</p>
        <p>Screen State: {screenState}</p>
      </div>
    </div>
  );
}

Arguments

Argument	Type	Description	Default value
options	object	Configuration options for idle detection	{}

Options

Option key	Type	Description	Default value
threshold	number	Minimum time in milliseconds before user is considered idle. Must be at least 60000ms (60 seconds) per W3C specification	60000
autoStart	boolean	Whether to automatically start idle detection when the hook mounts	false
requestPermission	boolean	Whether to automatically request permission for the Idle Detection API (required for native API usage)	false
onIdleChange	function	Callback function called when idle state changes. Receives object with {isIdle, userState, screenState}	undefined
onError	function	Callback function called when an error occurs during idle detection setup or operation. Receives Error object	undefined

Return value

Return value	Type	Description
isIdle	boolean	Whether the user is currently idle
userState	string	Current user activity state: "active" or "idle"
screenState	string	Current screen state: "locked" or "unlocked"
isSupported	boolean	Whether the native Idle Detection API is supported in the current browser
isPermissionGranted	boolean	Whether permission has been granted for the Idle Detection API
start	function	Function to manually start idle detection. Returns a Promise that resolves when detection starts
stop	function	Function to manually stop idle detection and reset states

useIdleDetectionApi

On this page