⬅️ Back to Table of Contents

📄 useIdle

📊 Analysis Summary

Metric	Count
🔧 Functions	4
📦 Imports	13
📊 Variables & Constants	2
📐 Interfaces	2

📚 Table of Contents

• Imports
• Variables & Constants
• Functions
• Interfaces

🛠️ File Location:

📂 packages/core/useIdle/index.ts

📦 Imports

Name	Source
ConfigurableEventFilter	@vueuse/shared
Stoppable	@vueuse/shared
TimerHandle	@vueuse/shared
ShallowRef	vue
ConfigurableWindow	../_configurable
WindowEventName	../useEventListener
createFilterWrapper	@vueuse/shared
throttleFilter	@vueuse/shared
timestamp	@vueuse/shared
shallowReadonly	vue
shallowRef	vue
defaultWindow	../_configurable
useEventListener	../useEventListener

---

Variables & Constants

Name	Type	Kind	Value	Exported
defaultEvents	WindowEventName[]	const	['mousemove', 'mousedown', 'resize', 'keydown', 'touchstart', 'wheel']	✗
oneMinute	60000	const	60_000	✗

---

Functions

useIdle(timeout: number, options: UseIdleOptions): UseIdleReturn

Tracks whether the user is being inactive.

Parameters:

• timeout any: default to 1 minute
• options any: IdleOptions

See: https://vueuse.org/useIdle

Raw JSDoc

/**
 * Tracks whether the user is being inactive.
 *
 * @see https://vueuse.org/useIdle
 * @param timeout default to 1 minute
 * @param options IdleOptions
 */

Calls:

• throttleFilter (from @vueuse/shared)
• shallowRef (from vue)
• timestamp (from @vueuse/shared)
• clearTimeout
• setTimeout
• createFilterWrapper (from @vueuse/shared)
• reset
• useEventListener (from ../useEventListener)
• onEvent
• start
• shallowReadonly (from vue)

Code

export function useIdle(
  timeout: number = oneMinute,
  options: UseIdleOptions = {},
): UseIdleReturn {
  const {
    initialState = false,
    listenForVisibilityChange = true,
    events = defaultEvents,
    window = defaultWindow,
    eventFilter = throttleFilter(50),
  } = options
  const idle = shallowRef(initialState)
  const lastActive = shallowRef(timestamp())
  const isPending = shallowRef(false)

  let timer: TimerHandle

  const reset = () => {
    idle.value = false
    clearTimeout(timer)
    timer = setTimeout(() => idle.value = true, timeout)
  }

  const onEvent = createFilterWrapper(
    eventFilter,
    () => {
      lastActive.value = timestamp()
      reset()
    },
  )

  if (window) {
    const document = window.document
    const listenerOptions = { passive: true }

    for (const event of events) {
      useEventListener(window, event, () => {
        if (!isPending.value)
          return
        onEvent()
      }, listenerOptions)
    }

    if (listenForVisibilityChange) {
      useEventListener(document, 'visibilitychange', () => {
        if (document.hidden || !isPending.value)
          return
        onEvent()
      }, listenerOptions)
    }

    start()
  }

  function start() {
    if (isPending.value) {
      return
    }
    isPending.value = true
    if (!initialState)
      reset()
  }
  function stop() {
    idle.value = initialState
    clearTimeout(timer)
    isPending.value = false
  }

  return {
    idle,
    lastActive,
    reset,
    stop,
    start,
    isPending: shallowReadonly(isPending),
  }
}

Internal helpers

Declared inside another function in this file.

reset(): void

Returns: void

Calls:

• clearTimeout
• setTimeout

Code

() => {
    idle.value = false
    clearTimeout(timer)
    timer = setTimeout(() => idle.value = true, timeout)
  }

start(): void

Returns: void

Calls:

• reset

Code

function start() {
    if (isPending.value) {
      return
    }
    isPending.value = true
    if (!initialState)
      reset()
  }

stop(): void

Returns: void

Calls:

• clearTimeout

Code

function stop() {
    idle.value = initialState
    clearTimeout(timer)
    isPending.value = false
  }

---

Interfaces

UseIdleOptions

Interface Code

export interface UseIdleOptions extends ConfigurableWindow, ConfigurableEventFilter {
  /**
   * Event names that listen to for detected user activity
   *
   * @default ['mousemove', 'mousedown', 'resize', 'keydown', 'touchstart', 'wheel']
   */
  events?: WindowEventName[]
  /**
   * Listen for document visibility change
   *
   * @default true
   */
  listenForVisibilityChange?: boolean
  /**
   * Initial state of the ref idle
   *
   * @default false
   */
  initialState?: boolean
}

Properties

Name	Type	Optional	Description
events	WindowEventName[]	✓	not shown
listenForVisibilityChange	boolean	✓	not shown
initialState	boolean	✓	not shown

UseIdleReturn

Interface Code

export interface UseIdleReturn extends Stoppable {
  idle: ShallowRef<boolean>
  lastActive: ShallowRef<number>
  reset: () => void
}

Properties

Name	Type	Optional	Description
idle	ShallowRef<boolean>	✗	not shown
lastActive	ShallowRef<number>	✗	not shown
reset	() => void	✗	not shown

---

Generated by Syntax Scribe