react-session-timer/README.md

A lightweight React library for handling user inactivity, session timeouts, and warning popups with customizable hooks and components.

# 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

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

## Usage

- 1. Wrap your app with SessionTimerProvider

```ts
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

```ts
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:

```ts
{
  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.