/react-idle-timer

User activity timer component

Primary LanguageJavaScriptMIT LicenseMIT

React Idle Timer

npm npm Travis Test Coverage Maintainability

JavaScript Style Guide

⚡️ Support for React 16
🚀 Support for Isomorphic React

Latest News

Welcome to version 4 of IdleTimer! We have performed a complete rewrite of our build system and a refactor/ clean up of the source code. After accepting many pull requests things started to get ugly. We added test coverage and continuous integration tools (travis and codeclimate) that will automatically enforce style and test future pull requests.

There are a few breaking changes in version 4:

  • The property startOnLoad has been renamed to startOnMount in order to make more sense in a react context.
  • The property activeAction has been renamed to onActive.
  • The property idleAction has been renamed to onIdle.

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 example example. 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'

export default class YourApp extends Component {
  constructor(props) {
    super(props)
    this.idleTimer = null
    this.onActive = this._onActive.bind(this)
    this.onIdle = this._onIdle.bind(this)
  }

  render() {
    return (
      <IdleTimer
        ref={ref => { this.idleTimer = ref }}
        element={document}
        onActive={this.onActive}
        onIdle={this.onIdle}
        timeout={1000 * 60 * 15}>

        <h1>Child Components</h1>

      </IdleTimer>
    )
  }

  _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())
  }
}

Documentation

To build the source code generated html docs run yarn docs and open docs/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 on idle.
  • onActive {Function} - Function to call on active.
  • element {Object} - Defaults to document, may pass a ref to another element.
  • startOnMount {Boolean} - Start the timer on component load. Defaults to true. Set to false to wait for user action before starting 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