Props

Props are the configuration options that can be passed to useIdleTimer or withIdleTimer. All props are optional and have sensible defaults. If a prop is updated dynamically, IdleTimer will be automatically restarted with the new set of properties. Examples of how they are used can be found in the hook and higher order component docs.

timeout#

description

Activity Timeout in milliseconds.

type
number
default
1200000

promptTimeout#

Deprecated
description

When the user becomes idle, the onPrompt and onPresenceChange event handlers are called. After the prompt timeout in milliseconds is reached, the onIdle and onPresenceChange event handlers are called.

type
number
default
0
deprecated
Deprecated in favor of promptBeforeIdle.

promptBeforeIdle#

description

The amount of milliseconds before idle timeout to call the onPrompt and onPresenceChange event handlers.

type
number
default
0

events#

description

DOM events to watch for activity on.

type
EventsType[]
default
[
  'mousemove',
  'keydown',
  'wheel',
  'DOMMouseScroll',
  'mousewheel',
  'mousedown',
  'touchstart',
  'touchmove',
  'MSPointerDown',
  'MSPointerMove',
  'visibilitychange'
]

immediateEvents#

description

DOM events that will bypass the timeout and immediately call onPrompt/onIdle. The events in this array take precedence over the events array.

type
EventsType[]
default
[]

onPresenceChange#

description

Function to call when the user's presence state changes. This provides a single function to handle all state changes. The IIdleTimer API is passed in as the second parameter.

type
(presence: PresenceType, idleTimer?: IIdleTimer) => void
default
() => {}
// The presence type definition
type PresenceType = { type: 'idle' } | { type: 'active', prompted: boolean }
// Example onPresenceChange implementation
import type { PresenceType } from 'react-idle-timer'


const onPresenceChange = (presence: PresenceType) => {
  const isIdle = presence.type === 'idle'
  const isActive = presence.type === 'active' && !presence.prompted
  const isPrompted = presence.type === 'active' && presence.prompted
}

onPrompt#

description

When promptTimeout is set, this function is called after the user becomes idle. This is useful for displaying a confirmation prompt. If the prompt timeout is reached, onIdle is then called. The IIdleTimer API is passed in as the second parameter.

type
(event?: Event, idleTimer?: IIdleTimer) => void
default
() => {}

onIdle#

description

Function to call when the user is idle. The IIdleTimer API is passed in as the second parameter.

type
(event?: Event, idleTimer?: IIdleTimer) => void
default
() => {}

onActive#

description

Function to call when the user becomes active. The IIdleTimer API is passed in as the second parameter.

type
(event?: Event, idleTimer?: IIdleTimer) => void
default
() => {}

onAction#

description

Function to call on user activity. The IIdleTimer API is passed in as the second parameter.

type
(event?: Event, idleTimer?: IIdleTimer) => void
default
() => {}

onMessage#

description

Function to call when a message event is received. The IIdleTimer API is passed in as the second parameter.

type
(data: any, idleTimer?: IIdleTimer) => void
default
() => {}

debounce#

description

Debounce the onAction function by setting delay in milliseconds.

type
number
default
0

throttle#

description

Throttle the onAction function by setting delay in milliseconds.

type
number
default
0

eventsThrottle#

description

Throttle the activity events. Useful if you are listening to mouse events. Helps to cut down on CPU usage.

type
number
default
200

element#

description

Element to bind activity listeners to.

type
Node
default
document

startOnMount#

description

Start the timer when the hook mounts.

type
boolean
default
true

startManually#

description

Require the timer to be started manually.

type
boolean
default
false

stopOnIdle#

description

Once the user goes idle the IdleTimer will not reset on user input. Instead, `start()` or `reset()` must be called manually to restart the timer.

type
boolean
default
false

disabled#

description

Disables the timer. Disabling the timer resets the internal state. When the property is set to true (enabled), the timer will be restarted, respecting the startManually property. If the timer is disabled, the control methods start, reset, activate, pause and resume will not do anything.

type
boolean
default
false

timers#

description

Set custom timers. By default main thread timers are used to allow for better tree shaking. If you want to use worker thread timers, import them from the package and set them here.

type
ITimers
default
{ setTimeout, clearTimeout, setInterval, clearInterval }

crossTab#

description

Enable cross tab event replication.

type
boolean
default
false

name#

description

Sets the name for the IdleTimer instance. This is required if you are running multiple instances with crossTab enabled.

type
string
default
idle-timer

syncTimers#

description

Syncs timers across all tabs. Timers are synced when user input is detected. The value of this property is the duration of the throttle on the sync operation. Setting to 0 disables the feature.

type
number
default
0

leaderElection#

description

Enables the Leader Election feature. Leader Election will assign one tab to be the leader. To determine if a tab is the leader, use the isLeader method.

type
boolean
default
false

Made withby Randy Lebeau