useUserIdle

A React Hook that helps to detect whether the user is idle or not.

Demo

Source
Is User Idle:
false
Last Active:
2025-05-22 09:56:06

Usage

See API for more details.

Source

Click links below to view source on GitHub.

API

const { lastActive, isIdle, reset } = useUserIdle(timeout, options)

Timeout

A number representing the time in milliseconds to consider the user as idle.

Options

export interface UseUserIdleOptions {
  /**
   * Event names that listen to for detected user activity
   *
   * @defaultValue ['mousemove', 'mousedown', 'resize', 'keydown', 'touchstart', 'wheel']
   */
  events?: WindowEventName[]
  /**
   * Listen for document visibility change
   *
   * @defaultValue true
   */
  watchVisibility?: boolean
  /**
   * Initial state of the ref idle
   *
   * @defaultValue false
   */
  initialState?: boolean
  /**
   * Reset the idle state immediately
   *
   * @defaultValue true
   */
  immediate?: boolean
}

Returns

Retuerns contain Pausable instance that can be paused, resumed.

See Pausable for more details.

export interface UseUserIdleReturns extends Pausable<[reset?: boolean], [reset?: boolean]> {
  /**
   * Whether the user is idle
   */
  isIdle: boolean
  /**
   * The timestamp of the last user activity
   */
  lastActive: MutableRefObject<number>
  /**
   * Reset the idle state
   *
   * @param restart - Whether to restart the idle timer,`true` by default.
   */
  reset: (restart?: boolean) => void
}