use-idle-prediction

⏳ A smart React hook that predicts when a user is likely to go idle based on their recent activity (keyboard, mouse, touch, clicks).

🚀 Install

npm install use-idle-prediction
# or
yarn add use-idle-prediction
# or
pnpm add use-idle-prediction
# or
bun add use-idle-prediction

📖 Usage

import { useIdlePrediction } from "use-idle-prediction";

export default function App() {
  const { isIdle, predictedIdleTime, lastActive, reset } = useIdlePrediction({
    idleTimeout: 5000, // 5s idle threshold
    historyLimit: 5,
  });

  return (
    <div style={{ padding: "2rem", fontFamily: "sans-serif" }}>
      <h1>🕒 useIdlePrediction Demo</h1>

      <p>
        <strong>Status:</strong> {isIdle ? "Idle 💤" : "Active ⚡"}
      </p>

      <p>
        <strong>Predicted idle in:</strong>{" "}
        {Math.round(predictedIdleTime / 1000)} seconds
      </p>

      <p>
        <strong>Last active at:</strong>{" "}
        {new Date(lastActive).toLocaleTimeString()}
      </p>

      <button onClick={reset}>Reset Prediction</button>
    </div>
  );
}

📌 Hook API

const { isIdle, predictedIdleTime, lastActive, reset } =
  useIdlePrediction(options);

Options

| Option | Type | Default | Description | | -------------- | ------ | ------- | --------------------------------------------------------- | | idleTimeout | number | 60000 | Time (ms) of inactivity that counts as idle | | historyLimit | number | 10 | Number of past activity intervals to store for prediction |

Returns

| Value | Type | Description | | ------------------- | -------- | --------------------------------------------- | | isIdle | boolean | Whether the user is currently idle | | predictedIdleTime | number | Estimated time (ms) before the user goes idle | | lastActive | number | Timestamp of last detected activity | | reset | function | Reset prediction + idle state |

📦 Use Cases

• 🔐 Auto-save form data before user goes idle.
• 🌙 Auto-dim screen or UI after predicted inactivity.
• 💬 Smarter chat presence (active → away prediction).
• 🎮 Games or apps that anticipate inactivity.