SupremeTechnopriest/react-idle-timer

---
title: useIdleTimer
description: React hook for functional React applications
---

The `useIdleTimer` hook can be used with functional React components. It takes 
[IIdleTimerProps](/docs/api/props) as configuration options and returns 
[IIdleTimer](/docs/api/methods).

## Import
```js
import { useIdleTimer } from 'react-idle-timer'
```

## Usage

A minimal example with the bare essential configuration.

```js
import { useIdleTimer } from 'react-idle-timer'

export const App = () => {
  const onPresenceChange = (presence) => {
    // Handle state changes in one function
  }

  const idleTimer = useIdleTimer({ onPresenceChange })

  return (
    <HomePage />
  )
}
```

A full example with all available props and methods. Props are set to their
default value.

```js
import { useIdleTimer } from 'react-idle-timer' 

export const App = () => {
  const onPresenceChange = (presence) => {
    // Handle state changes in one function
  }

  const onPrompt = () => {
    // Fire a Modal Prompt
  }

  const onIdle = () => {
    // Close Modal Prompt
    // Do some idle action like log out your user
  }

  const onActive = (event) => {
    // Close Modal Prompt
    // Do some active action
  }

  const onAction = (event) => {
    // Do something when a user triggers a watched event
  }

  const {
    start,
    reset,
    activate,
    pause,
    resume,
    isIdle,
    isPrompted,
    isLeader,
    isLastActiveTab,
    getTabId,
    getRemainingTime,
    getElapsedTime,
    getLastIdleTime,
    getLastActiveTime,
    getIdleTime,
    getTotalIdleTime,
    getActiveTime,
    getTotalActiveTime
  } = useIdleTimer({
    onPresenceChange,
    onPrompt,
    onIdle,
    onActive,
    onAction,
    timeout: 1000 * 60 * 20,
    promptBeforeIdle: 0,
    events: [
      'mousemove',
      'keydown',
      'wheel',
      'DOMMouseScroll',
      'mousewheel',
      'mousedown',
      'touchstart',
      'touchmove',
      'MSPointerDown',
      'MSPointerMove',
      'visibilitychange',
      'focus'
    ],
    immediateEvents: [],
    debounce: 0,
    throttle: 0,
    eventsThrottle: 200,
    element: document,
    startOnMount: true,
    startManually: false,
    stopOnIdle: false,
    crossTab: false,
    name: 'idle-timer',
    syncTimers: 0,
    leaderElection: false
  })
  return (
    <HomePage />
  )
}
```

## Examples

<Flex direction='column' mt={8}>
  <CodeSandboxButton name='idle-timer-hook-03790m'>Idle Detection</CodeSandboxButton>
  <CodeSandboxButton name='activity-detection-tmn5bp'>Activity Detection</CodeSandboxButton>
  <CodeSandboxButton name='cross-tab-2e1tbp'>Cross Tab Support</CodeSandboxButton>
  <CodeSandboxButton name='confirm-prompt-y8ew9s'>Confirm Prompt</CodeSandboxButton>
  <CodeSandboxButton name='presence-change-handler-2grrwh'>Presence Change Handler</CodeSandboxButton>
</Flex>