react-idle-timer

What is react-idle-timer?

The react-idle-timer package is a React component that helps you detect and manage idle state in your application. It allows you to perform actions based on user inactivity, such as logging out the user, showing a warning message, or triggering any other custom behavior.

What are react-idle-timer's main functionalities?

Detecting Idle State

This feature allows you to detect when the user becomes idle. The `useIdleTimer` hook is used to set a timeout (in this case, 15 minutes) and a callback function (`handleOnIdle`) that gets called when the user is idle.

import React from 'react';
import { useIdleTimer } from 'react-idle-timer';

const App = () => {
  const handleOnIdle = () => {
    console.log('User is idle');
  };

  const { getRemainingTime, getLastActiveTime } = useIdleTimer({
    timeout: 1000 * 60 * 15,
    onIdle: handleOnIdle,
    debounce: 500
  });

  return (
    <div>
      <p>Remaining time: {getRemainingTime()}</p>
      <p>Last active time: {getLastActiveTime()}</p>
    </div>
  );
};

export default App;

Resetting Idle Timer

This feature allows you to manually reset the idle timer. The `reset` function from the `useIdleTimer` hook can be called to reset the timer, for example, when a user performs a specific action like clicking a button.

import React from 'react';
import { useIdleTimer } from 'react-idle-timer';

const App = () => {
  const { reset } = useIdleTimer({
    timeout: 1000 * 60 * 15,
    onIdle: () => console.log('User is idle'),
    debounce: 500
  });

  return (
    <div>
      <button onClick={reset}>Reset Timer</button>
    </div>
  );
};

export default App;

Pausing and Resuming Idle Timer

This feature allows you to pause and resume the idle timer. The `pause` and `resume` functions from the `useIdleTimer` hook can be used to control the timer based on specific user actions.

import React from 'react';
import { useIdleTimer } from 'react-idle-timer';

const App = () => {
  const { pause, resume } = useIdleTimer({
    timeout: 1000 * 60 * 15,
    onIdle: () => console.log('User is idle'),
    debounce: 500
  });

  return (
    <div>
      <button onClick={pause}>Pause Timer</button>
      <button onClick={resume}>Resume Timer</button>
    </div>
  );
};

export default App;

Other packages similar to react-idle-timer

idle-js

The idle-js package is a lightweight JavaScript library for detecting user inactivity. It provides similar functionality to react-idle-timer but is not specifically designed for React. It can be used in any JavaScript application to detect idle state and perform actions based on user inactivity.

react-idle

The react-idle package is another React component for detecting user inactivity. It offers similar features to react-idle-timer, such as detecting idle state and performing actions based on user inactivity. However, it may have a different API and set of features compared to react-idle-timer.

README

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 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'
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 with shouldComponentUpdate you should avoid using IdleTimer as a wrapper component.
• 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.

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 when user is now idle.
• onActive {Function} - Function to call when user is no longer idle.
• onActive {Function} - Function to call on user action.
• debounce {Number} - Debounce the onActive function with delay in milliseconds. Defaults to 0. Cannot be set if throttle is set.
• throttle {Number} - Throttle the onActive function with delay in milliseconds. Defaults to 0. Cannot be set if debounce 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 to false 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 call reset() 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

Changelog

4.1.0

⚡️ Features

• Add property stopOnIdle defaults to false. Setting to true will prevent user activity from restarting the IdleTimer once it has gone idle. This useful if you want to do some custom async stuff before the IdleTimer gets restarted. In order to restart the IdleTimer call reset() on your ref.
• Add event handler onActive which enables reporting of all user activity from IdleTimer. The built in debounce or throttle properties will help increase performance if you are using the onActive event. By default debounce and throttle are off. Only one can be enabled at a time.
• Add property debounce defaults to 0. Set the onActive debounce delay in milliseconds. The throttle property cannot be set if this property is set.
• Add property throttle defaults to 0. Set the onActive throttle delay in milliseconds. The debounce property cannot be set if this property is set.