React Idle Timer
⚡️ Support for React 16
🚀 Support for Isomorphic React
Latest News
Version 4.1.0
brings two of the most requested features to IdleTimer
:
☝️ You can now use IdleTimer
as a generic activity monitor via the new onAction
event handler. We recommend using one of the built in debounce
or throttle
properties if you dont need every single update. It really improves performance.
✌️ Added a property stopOnIdle
that allows developer intervention between the idle and active states. Good for waiting for an async task to complete before restarting the IdleTimer
. If this option is set, you will have to call reset()
manually to restart IdleTimer
.
For the full patch notes please refer to the CHANGELOG
Installation
yarn add react-idle-timer
or
npm install react-idle-timer --save
Usage
Run
yarn example
to build and run the exampleexample
. The example is a create-react-app project. IdleTimer is implemented in the App Component.
import React, { Component } from 'react'
import IdleTimer from 'react-idle-timer'
import App from './App'
export default class YourApp extends Component {
constructor(props) {
super(props)
this.idleTimer = null
this.onAction = this._onAction.bind(this)
this.onActive = this._onActive.bind(this)
this.onIdle = this._onIdle.bind(this)
}
render() {
return (
<div>
<IdleTimer
ref={ref => { this.idleTimer = ref }}
element={document}
onActive={this.onActive}
onIdle={this.onIdle}
onAction={this.onAction}
debounce={250}
timeout={1000 * 60 * 15} />
{/* your app here */}
</div>
)
}
_onAction(e) {
console.log('user did something', e)
}
_onActive(e) {
console.log('user is active', e)
console.log('time remaining', this.idleTimer.getRemainingTime())
}
_onIdle(e) {
console.log('user is idle', e)
console.log('last active', this.idleTimer.getLastActiveTime())
}
}
Migration from v3 to v4
There are a few breaking changes in version 4:
- Although still capable of rendering children, as of version 4 we dont pass children to
IdleTimer
. Unless you are really good withshouldComponentUpdate
you should avoid usingIdleTimer
as a wrapper component. - The property
startOnLoad
has been renamed tostartOnMount
in order to make more sense in a React context. - The property
activeAction
has been renamed toonActive
. - The property
idleAction
has been renamed toonIdle
.
Documentation
To build the source code generated html docs run
yarn docs
and opendocs/index.html
in any browser. A markdown version is available here.
Default Events
These events are bound by default:
- mousemove
- keydown
- wheel
- DOMMouseScroll
- mouseWheel
- mousedown
- touchstart
- touchmove
- MSPointerDown
- MSPointerMove
Props
- timeout {Number} - Idle timeout in milliseconds.
- events {Array} - Events to bind. See default events for list of defaults.
- onIdle {Function} - Function to call when user is now idle.
- onActive {Function} - Function to call when user is no longer idle.
- onAction {Function} - Function to call on user action.
- debounce {Number} - Debounce the
onActive
function with delay in milliseconds. Defaults to0
. Cannot be set ifthrottle
is set. - throttle {Number} - Throttle the
onActive
function with delay in milliseconds. Defaults to0
. Cannot be set ifdebounce
is set. - element {Object} - Defaults to document, may pass a ref to another element.
- startOnMount {Boolean} - Start the timer when the component mounts. Defaults to
true
. Set tofalse
to wait for user action before starting timer. - stopOnIdle {Boolean} - Stop the timer when user goes idle. Defaults to
false
. If set to true you will need to manually callreset()
to restart the timer. - passive {Boolean} - Bind events in passive mode. Defaults to
true
. - capture {Boolean} - Bind events in capture mode. Defaults to
true
.
Methods
- reset() {Void} - Resets the idleTimer
- pause() {Void} - Pauses the idleTimer
- resume() {Void} - Resumes a paused idleTimer
- getRemainingTime() {Number} - Returns the remaining time in milliseconds
- getElapsedTime() {Number} - Returns the elapsed time in milliseconds
- getLastActiveTime() {Number} - Returns the
Timestamp
the user was last active - isIdle() {Boolean} - Returns whether or not user is idle