use-idle-redirect
v1.0.0
Published
React hooks for inactivity timeouts: warn before session expiry with a live countdown, then log out / redirect. Synced across browser tabs, throttled, SSR-safe. Bank-style auto logout in a few lines.
Maintainers
Readme
use-idle-redirect
Bank-style auto logout for React. Warn the user before their session expires with a live countdown, then log out and redirect — synced across all open tabs.
import { useIdleRedirect } from 'use-idle-redirect';
export function SessionGuard() {
const { isWarning, remaining, reset } = useIdleRedirect({
timeout: 15 * 60_000, // 15 minutes of inactivity
warningBefore: 60_000, // warn during the last minute
onIdle: () => fetch('/api/logout', { method: 'POST' }),
redirectTo: '/login', // → /login?reason=idle&returnTo=/current/page
});
if (!isWarning) return null;
return (
<div role="alertdialog" aria-live="assertive">
You will be signed out in {Math.ceil(remaining / 1000)} seconds.
<button onClick={reset}>Stay signed in</button>
</div>
);
}Put <SessionGuard /> once in your authenticated layout.
Install
npm install use-idle-redirectFeatures
- Warning stage with a live
remainingcountdown (updates every second only while warning). - Cross-tab: activity in any tab keeps all tabs signed in (
BroadcastChannel+localStoragefallback). - Correct in background tabs: status is computed from timestamps, so throttled timers don't cause late or early logouts.
- Throttled listeners (
mousemove,keydown,scroll,touchstart, …) — negligible overhead. - Once idle, stray mouse moves don't "wake" the session; only
reset()does. - SSR-safe.
API
useIdleRedirect(options)
All useIdleTimer options plus:
| Option | Default | Description |
| --- | --- | --- |
| redirectTo | '/login' | Target URL |
| withReturnTo | true | Adds ?reason=idle&returnTo=<path> |
| onIdle | – | Async logout logic, awaited before redirect |
| navigate | location.assign | Custom navigation, e.g. React Router navigate or Next router.replace |
useIdleTimer(options) — just the timer
| Option | Default | Description |
| --- | --- | --- |
| timeout | 900000 (15 min) | Inactivity until idle |
| warningBefore | 60000 | Warning stage length (0 = none) |
| onWarn(remaining), onIdle(), onActive() | – | Transition callbacks |
| events | mouse/keyboard/touch/scroll | Activity events |
| crossTab | true | Sync between tabs |
| storageKey | 'idle-timer' | Sync channel name |
| throttle | 500 | Listener throttle, ms |
| enabled | true | Disable (e.g. on public pages) |
Returns { status: 'active' | 'warning' | 'idle', isIdle, isWarning, remaining, lastActive, reset(), pause(), resume() }.
Next.js / React Router
const router = useRouter(); // next/navigation
useIdleRedirect({ timeout: 10 * 60_000, navigate: (url) => router.replace(url), onIdle: signOut });License
MIT
