react-idle-timeout

Lightweight, cross-tab-aware React idle timeout with optional unstyled UI.

• Cross-tab by default — activity in any tab resets all tabs
• Zero dependencies — only peer deps on react and react-dom
• Tiny API — one hook, one context provider, one dialog component
• Unstyled dialog — uses native <dialog>, style it however you want
• TypeScript — full type definitions included

Install

npm install react-idle-timeout

Quick Start

Hook (headless)

import { useIdleTimeout } from 'react-idle-timeout';

function App() {
  const { isWarning, remainingTime, reset } = useIdleTimeout({
    timeout: 15 * 60 * 1000,      // 15 minutes
    warningDuration: 30 * 1000,    // 30 second warning
    onIdle: () => {
      // Session expired — log the user out
      logout();
    },
    onWarning: () => {
      console.log('User is about to be logged out');
    },
  });

  if (isWarning) {
    return (
      <div>
        <p>Session expires in {remainingTime} seconds</p>
        <button onClick={reset}>Stay Logged In</button>
      </div>
    );
  }

  return <YourApp />;
}

With the built-in dialog

import { useIdleTimeout, IdleTimeoutDialog } from 'react-idle-timeout';

function App() {
  const { isWarning, remainingTime, reset } = useIdleTimeout({
    timeout: 15 * 60 * 1000,
    warningDuration: 30 * 1000,
    onIdle: () => logout(),
  });

  return (
    <>
      <YourApp />
      <IdleTimeoutDialog
        isOpen={isWarning}
        remainingTime={remainingTime}
        onStayActive={reset}
        onIdle={() => logout()}
      />
    </>
  );
}

With context provider

import { IdleTimeoutProvider, useIdleTimeoutContext, IdleTimeoutDialog } from 'react-idle-timeout';

function Root() {
  return (
    <IdleTimeoutProvider
      timeout={15 * 60 * 1000}
      warningDuration={30 * 1000}
      onIdle={() => logout()}
    >
      <App />
      <TimeoutWarning />
    </IdleTimeoutProvider>
  );
}

function TimeoutWarning() {
  const { isWarning, remainingTime, reset } = useIdleTimeoutContext();

  return (
    <IdleTimeoutDialog
      isOpen={isWarning}
      remainingTime={remainingTime}
      onStayActive={reset}
      onIdle={() => logout()}
    />
  );
}

API

useIdleTimeout(options?)

| Option | Type | Default | Description | |--------|------|---------|-------------| | timeout | number | 900000 (15min) | Idle timeout in milliseconds | | warningDuration | number | 30000 (30s) | Warning period before idle. Set to 0 to disable. | | events | string[] | ['mousedown', 'mousemove', 'keydown', 'scroll', 'touchstart', 'click'] | DOM events that count as activity | | throttle | number | 1000 | Minimum ms between processing activity events | | storageThrottle | number | 30000 | Minimum ms between localStorage writes | | crossTab | boolean | true | Enable cross-tab synchronisation | | storageKeyPrefix | string | 'idle' | Prefix for localStorage keys | | startOnMount | boolean | true | Start timer automatically | | onIdle | () => void | — | Called when timeout expires | | onWarning | () => void | — | Called when warning period begins | | onActive | () => void | — | Called when user returns from idle/warning |

Returns:

| Property | Type | Description | |----------|------|-------------| | isIdle | boolean | Whether the timeout has expired | | isWarning | boolean | Whether the warning period is active | | remainingTime | number \| null | Seconds remaining until idle | | start() | () => void | Start the timer (use with startOnMount: false) | | reset() | () => void | Reset the timer as if the user just interacted | | pause() | () => void | Pause the timer | | resume() | () => void | Resume a paused timer | | destroy() | () => void | Stop and clean up |

<IdleTimeoutProvider>

Accepts all useIdleTimeout options as props, plus children. Provides the idle timeout API via context.

useIdleTimeoutContext()

Access the idle timeout API from context. Must be used within an <IdleTimeoutProvider>.

<IdleTimeoutDialog>

Unstyled dialog component using the native <dialog> element.

| Prop | Type | Default | Description | |------|------|---------|-------------| | isOpen | boolean | — | Whether the dialog is open | | remainingTime | number \| null | — | Seconds remaining | | onStayActive | () => void | — | Called when user clicks "Stay Logged In" | | onIdle | () => void | — | Called when user clicks "Log Out" | | className | string | — | Additional CSS class | | title | string | 'Session Timeout Warning' | Dialog title | | message | string | 'Your session is about to expire due to inactivity.' | Dialog message | | stayActiveText | string | 'Stay Logged In' | Stay button text | | idleText | string | 'Log Out' | Idle button text |

CSS classes for styling:

.idle-timeout-dialog          /* the <dialog> element */
.idle-timeout-dialog__title   /* the heading */
.idle-timeout-dialog__message /* the description */
.idle-timeout-dialog__timer   /* the countdown */
.idle-timeout-dialog__actions /* button container */
.idle-timeout-dialog__stay    /* "Stay Logged In" button */
.idle-timeout-dialog__idle    /* "Log Out" button */

Example

A full working example is in the example/ directory. It demonstrates:

• Hook usage with the built-in dialog
• Event logging
• Manual reset, pause, and resume controls
• Cross-tab sync (open in multiple tabs to see it)

To run it:

# From the repo root
npm run build               # Build the library first
cd example
npm install
npm run dev                 # Opens at http://localhost:5173

The example uses a 10-second timeout with a 5-second warning so you can see the behaviour quickly.

How Cross-Tab Works

Activity detection and timeout synchronisation happen across all tabs on the same origin:

1. Activity broadcast — when a user interacts with any tab, the activity timestamp is written to localStorage. Other tabs pick this up via the storage event and reset their timers.

2. Leader election — the Web Locks API ensures only one tab (the "leader") handles the actual logout. If the leader tab closes, another tab automatically takes over.

3. Graceful fallback — if Web Locks is unavailable, all tabs act independently (same behaviour, slightly redundant). The localStorage coordination still prevents multiple simultaneous logouts.

Browser Support

Works in all modern browsers. The Web Locks API is supported in Chrome 69+, Firefox 96+, Safari 15.4+, and Edge 79+. Older browsers fall back gracefully to single-tab behaviour.

License

MIT