react-session-timer

A React session timer package that tracks user session time, shows a warning modal before expiration, and provides hooks to extend or reset sessions. Perfect for apps that require auto-logout functionality.

⏰ Easy session management with one hook — start, extend, reset, and stop sessions programmatically.

Features

• Countdown session timer with customizable duration
• Warning modal before session expires
• Easy-to-use hook and context for global session state
• Extend, reset, and stop session programmatically
• Fully typed with TypeScript

Installation

npm install react-session-timer
# or
yarn add react-session-timer

Usage

• 1. Wrap your app with SessionTimerProvider

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

const Root = () => (
  <SessionTimerProvider
    duration={300} // session duration in seconds (5 minutes)
    warningThreshold={60} // show warning when 60 seconds left
    onTimeout={() => alert("Session expired")}
    onWarning={() => console.log("Warning: session about to expire")}
  >
    <App />
  </SessionTimerProvider>
);

export default Root;

• 2. Use the hook to access session state

import React from "react";
import { useSessionTimer } from "react-session-timer";
import WarningModal from "react-session-timer/dist/components/WarningModal";

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

  const handleExtend = () => extend(120); // add 2 more minutes
  const handleLogout = () => stop(); // stop session (could redirect to login)

  return (
    <div>
      <h1>Dashboard</h1>
      <p>Time remaining: {remainingTime} seconds</p>
      <WarningModal
        remainingTime={remainingTime}
        visible={isWarningVisible}
        onExtend={handleExtend}
        onLogout={handleLogout}
      />
    </div>
  );
};

export default Dashboard;

API

SessionTimerProvider props

| Prop | Type | Default | Description | | ------------------ | ------------ | ------- | ----------------------------------------------------------------- | | duration | number | — | Total session time in seconds (e.g. 300 for 5 minutes). | | warningThreshold | number | 60 | Time (in seconds) before expiration to trigger the warning modal. | | onTimeout | () => void | — | Callback fired when the session expires. | | onWarning | () => void | — | Callback fired when the warning threshold is reached. | | children | ReactNode | — | The app or components wrapped by the provider. |

Hook: useSessionTimer()

Returns:

{
  remainingTime: number;
  isWarningVisible: boolean;
  start: () => void;
  reset: () => void;
  extend: (extraSeconds?: number) => void;
  stop: () => void;
}

Component: WarningModal

Props:

• remainingTime: number – seconds left
• visible: boolean – show/hide modal
• onExtend: () => void – extend session
• onLogout: () => void – logout or stop session

Notes

• You can rotate or extend the session duration dynamically using extend().
• Works with React 18+ and TypeScript.
• Compatible with browser environments only.