react-idle-timer

The Cross Tab API has been simplified in v5. The crossTab prop now accepts a boolean to enable or disable the feature. Most configuration options from v4 are now set to sane defaults.

Syncing Timers

Use the syncTimers property (a number representing milliseconds) to replicate user actions across all tabs, keeping timeouts in sync. A value of 200 is a recommended starting point to balance synchronization with messaging overhead.

Isolating Instances

If using multiple IdleTimer instances on the same page, use the name prop to ensure cross-tab events are isolated to their respective instances.

// Hook with Cross Tab and Syncing enabled
const idleTimer = useIdleTimer({
  crossTab: true,
  syncTimers: 200
})

// Multiple isolated instances
const logoutTimer = useIdleTimer({
  timeout: 1000 * 60 * 30,
  crossTab: true,
  syncTimers: 200,
  name: 'logout-timer'
})

const activityTimer = useIdleTimer({
  timeout: 1000 * 60 * 5,
  crossTab: true,
  syncTimers: 200,
  name: 'activity-timer'
})

You can automatically prompt a user before they go idle (e.g., showing a modal to ask if they are still there).

Key properties and methods:

• promptBeforeIdle: The amount of time (in ms) before the timeout is reached that the prompt should trigger.
• onPrompt(): Event handler called when the prompt state is entered. All other events are disabled while the prompt is active.
• onIdle(): Event handler called when the full timeout is reached.
• onActive(): Event handler called if the user interacts/activates while in the prompted state.
• isPrompted(): State getter to check if the user is currently in the prompted state.
• getRemainingTime(): Returns the remaining time until the idle state is reached.
• activate(): Manually resets the timer and triggers onActive if the user was idle or prompted.

export function App () {
  const timeout = 1000 * 60 * 30
  const promptBeforeIdle = 1000 * 30
  const [open, setOpen] = useState(false)
  const [remaining, setRemaining] = useState(0)

  const onPrompt = () => {
    setOpen(true)
    setRemaining(promptTimeout)
  }

  const onIdle = () => {
    setOpen(false)
    setRemaining(0)
  }

  const onActive = () => {
    setOpen(false)
    setRemaining(0)
  }

  const { getRemainingTime, isPrompted, activate } = useIdleTimer({
    timeout,
    promptBeforeIdle,
    onPrompt,
    onIdle,
    onActive
  })

  const handleStillHere = () => {
    setOpen(false)
    activate()
  }

  useEffect(() => {
    const interval = setInterval(() => {
      if (isPrompted()) {
        setRemaining(Math.ceil(getRemainingTime() / 1000))
      }
    }, 1000)
    return () => clearInterval(interval)
  }, [getRemainingTime, isPrompted])

  return (
    <div className='modal' style={{ display: open ? 'block': 'none' }}>
      <p>Logging you out in {remaining} seconds</p>
      <button onClick={handleStillHere}>Im Still Here</button>
    </div>
  )
}

IdleTimer enforces strict commit message guidelines. Messages must use the present tense and imperative mood (e.g., "Add feature" instead of "Added feature"), and the first line must be 72 characters or less.

Every commit must start with an applicable emoji to categorize the change: