react-session-timer

Accurate session-expiry warnings for React—without locking you into an auth stack or UI kit.

Show the right time left, warn users once, let them extend their session, then run your existing logout flow. The timer is deadline-based, so it catches up when a browser tab returns from the background.

const { remainingTime, isWarningVisible, extend } = useSessionTimer();

Built for session-expiry UX

react-session-timer gives your app the missing client-side experience around an expiry your auth system already controls:

• Deadline-accurate. Remaining time is calculated from an absolute deadline, not a fragile decrementing counter.
• Fits your UI. Use the headless hook with your design system, or start with the included accessible WarningModal.
• Predictable controls. start, reset, extend, and stop have clear, documented behavior.
• Safe event handling. Warning and timeout handlers fire once per session, outside React state updates.
• Light integration. No UI framework, router, or authentication-provider dependency.

When it is the right choice

Choose it when you already own login, token refresh, and logout, and want a polished expiry-warning experience without adopting a larger auth or UI package.

| If you need… | Best fit | | --- | --- | | A deadline-accurate warning timer that works with your existing auth flow | react-session-timer | | User-idle detection from mouse, keyboard, or touch events | An inactivity/idle-tracking library | | Token validation, refresh rotation, roles, or server logout | Your auth provider and backend | | A fully themed dialog system | Your existing design system or component library | | Shared expiry across tabs or devices | A server-issued expiry, optionally with your own browser coordination |

It deliberately focuses on client-side countdown state. For user-idle detection, multi-tab coordination, token validation, or server logout, use the appropriate layer alongside it.

Installation

npm install react-session-timer

react and react-dom are peer dependencies.

Quick start

Wrap the part of the application that needs session state.

import { SessionTimerProvider } from "react-session-timer";
import { App } from "./App";

export function Root() {
  return (
    <SessionTimerProvider
      duration={300}
      warningThreshold={60}
      autoStart
      onWarning={() => console.info("Session expires soon")}
      onTimeout={() => {
        // Clear local auth state and redirect. Keep server expiry authoritative.
        window.location.assign("/login");
      }}
    >
      <App />
    </SessionTimerProvider>
  );
}

Use the state with your own dialog, or use the exported WarningModal.

import { WarningModal, useSessionTimer } from "react-session-timer";

export function SessionExpiryNotice() {
  const { remainingTime, isWarningVisible, extend, stop } = useSessionTimer();

  return (
    <WarningModal
      visible={isWarningVisible}
      remainingTime={remainingTime}
      onExtend={() => extend(120)}
      onLogout={() => {
        stop();
        window.location.assign("/login");
      }}
    />
  );
}

Behaviour you can rely on

• The visible time is calculated from a real deadline and catches up when the page becomes visible again.
• onWarning and onTimeout each fire once for a session.
• start() always creates a new session using duration.
• reset() restores duration while preserving whether the timer was running.
• extend() adds time and resumes a stopped or expired timer.
• stop() clears the deadline and dismisses the warning.

API

SessionTimerProvider

| Prop | Type | Default | Meaning | | --- | --- | --- | --- | | duration | number | required | Whole, non-negative session length in seconds. | | warningThreshold | number | 60 | Whole, non-negative seconds remaining at which the warning is shown. | | autoStart | boolean | false | Start a fresh session when the provider mounts. | | onWarning | () => void | — | Called once for each session when the warning threshold is reached. | | onTimeout | () => void | — | Called once when a running session reaches zero. |

useSessionTimer()

const {
  remainingTime,
  isRunning,
  isWarningVisible,
  start,
  reset,
  extend,
  stop,
} = useSessionTimer();

| Value or action | Meaning | | --- | --- | | remainingTime | Whole seconds remaining, rounded up for display. | | isRunning | Whether the countdown is active. | | isWarningVisible | Whether the warning threshold has been reached for the active session. | | start() | Starts a new session using duration; it always resets the countdown. | | reset() | Restores duration. It preserves the current running/stopped state. | | extend(seconds = 60) | Adds whole, positive seconds. It resumes a stopped or expired timer. | | stop() | Stops the timer, clears its deadline, and hides the warning. |

Changing the provider's duration prop affects the next start() or reset() call. It intentionally does not alter a session already in progress.

WarningModal

The optional modal is exported as a named import:

import { WarningModal } from "react-session-timer";

It has a dialog role, moves focus into the dialog, restores focus when dismissed, keeps keyboard focus within its buttons, and supports Escape to invoke onLogout. For a branded product experience, render your own dialog from isWarningVisible instead.

Security note

Use onTimeout to clear local client state and redirect, but keep expiry enforcement and refresh-token rotation on the server. A browser timer is a user-experience feature, not an access-control boundary.

Development

npm run test
npm run build

License

MIT © mmarkova.an.y