How to Make an Idle Timer in React App

Idle timers are essential for web applications that handle sensitive user data or require authentication. By automatically detecting user inactivity and taking appropriate actions--such as logging out users or showing warnings--idle timers enhance security and improve user experience. This guide explores how to implement an idle timer in React using modern best practices and the react-idle-timer library.

What you'll learn:

• Installing and configuring react-idle-timer
• Implementing idle detection hooks
• Cross-tab synchronization patterns
• Integration with authentication systems
• Performance optimization techniques

Implementing proper session management is a fundamental aspect of professional web development that protects both users and applications from unauthorized access while maintaining a seamless user experience.

Installing and Setting Up react-idle-timer

The react-idle-timer package provides a robust, well-maintained solution for implementing idle detection in React applications. Available through npm, this library offers both a hook-based API and a higher-order component pattern, making it compatible with various React application architectures.

Installation

npm install react-idle-timer

The package handles the complexity of tracking user activity across different event types and browser states, providing a reliable foundation for idle detection.

Basic Configuration Options

The useIdleTimer hook accepts several configuration options:

These configuration options allow you to tailor idle detection to your specific security requirements and user experience goals.

Handling Different Event Types

The react-idle-timer library monitors a comprehensive set of events to detect user activity:

Default Events Tracked

• Mouse events: mousemove, mousedown, mouseup, scroll, wheel
• Keyboard events: keydown, keyup, keypress
• Touch events: touchstart, touchmove, touchend
• Visibility events: visibilitychange, focus, blur

Customizing Tracked Events

You can customize which events trigger activity detection:

const { reset } = useIdleTimer({
 timeout: 1000 * 60 * 10,
 events: ['mousemove', 'keydown', 'click']
});

This customization proves useful when your application includes automated interactions that shouldn't reset the idle timer, such as auto-saving drafts or refreshing data displays.

Performance Optimization

For high-frequency events, use throttling to reduce CPU usage:

const { reset } = useIdleTimer({
 throttle: 1000, // Only process events once per second
 timeout: 1000 * 60 * 15
});

Optimizing event handling is part of building performant React applications that scale effectively.

Advanced Features: Cross-Tab Synchronization

Cross-tab synchronization enables coordinated idle detection across multiple browser tabs running the same application. When users have your application open in multiple tabs, cross-tab synchronization ensures consistent idle state across all tabs.

How It Works

The cross-tab functionality uses the Broadcast Channel API and LocalStorage to communicate between tabs:

• Activity in one tab resets the idle timer in all tabs
• Logout in one tab logs out from all tabs
• Leader election handles timeout coordination
• Automatic fallback for older browsers

Implementation

const {
 isIdle,
 isLeader,
 getTabId
} = useIdleTimer({
 crossTab: true,
 name: 'my-app-session',
 timeout: 1000 * 60 * 15,
 onIdle: () => logoutFromAllTabs()
});

Key Methods for Cross-Tab

• isLeader(): Check if current tab is the leader for coordination
• getTabId(): Get unique identifier for this tab
• Automatic synchronization of idle state across tabs

This advanced pattern is essential for AI-powered applications that manage sensitive user sessions across multiple interfaces.

Integration with Authentication Systems

Integrating idle timers with authentication systems requires coordination between session timeout logic and auth token management.

JWT-Based Authentication

const { onIdle } = useIdleTimer({
 timeout: 1000 * 60 * 15,
 onIdle: async () => {
 // Clear tokens from storage
 localStorage.removeItem('accessToken');
 localStorage.removeItem('refreshToken');
 
 // Clear auth state
 dispatch(logout());
 
 // Redirect to login
 router.push('/login?reason=idle');
 }
});

Session Cookie Authentication

const { onIdle } = useIdleTimer({
 timeout: 1000 * 60 * 15,
 onIdle: async () => {
 // Invalidate server-side session
 await fetch('/api/auth/logout', { method: 'POST' });
 
 // Redirect
 router.push('/login');
 }
});

Extending Sessions

Provide users the ability to extend their session before automatic logout:

const { reset, getRemainingTime } = useIdleTimer({
 timeout: 1000 * 60 * 15,
 onIdle: handleLogout
});

const handleExtendSession = async () => {
 // Optionally refresh token server-side
 await refreshAuthToken();
 
 // Reset idle timer
 reset();
};

Best Practices for React Idle Timers

Security Guidelines

1. Timeout Duration: Match timeout to data sensitivity--shorter for financial/healthcare, longer for general use
2. Warning Modal: Always show countdown warnings before automatic logout
3. Token Cleanup: Clear all authentication tokens and session data on logout
4. HTTPS Only: Ensure idle timer functionality works correctly with secure contexts

User Experience

// Multi-stage idle detection
const TIMEOUT = 1000 * 60 * 15; // 15 minutes
const WARNING_BEFORE = 1000 * 60 * 2; // 2 minute warning

const {
 isIdle,
 isPrompted
} = useIdleTimer({
 timeout: TIMEOUT,
 promptBeforeIdle: WARNING_BEFORE,
 onIdle: handleLogout,
 onPrompt: showCountdownModal
});

Performance Tips

• Throttle high-frequency events (mousemove, scroll) to reduce CPU usage
• Debounce keyboard events in text-heavy applications
• Close connections (WebSockets, SSE) when user becomes idle
• Clean up resources in onIdle callback to prevent memory leaks

Testing Considerations

• Test across different browsers and devices
• Verify behavior with multiple tabs open
• Test with various activity patterns (mouse only, keyboard only, mixed)
• Verify timeout accuracy under system load

Following these best practices ensures your session management aligns with comprehensive SEO strategies that prioritize both security and user experience.

Sources

1. LogRocket: How to make an idle timer for your React app - Comprehensive tutorial covering react-idle-timer package usage
2. IdleTimer.dev: useIdleTimer API Documentation - Official API documentation with complete props reference
3. NPM: react-idle-timer - Package information and installation instructions