react-native-session-timeout

A comprehensive React Native library for inactivity detection and idle app monitoring with automatic session timeout management, customizable warning UI support, and full Android 10+ compatibility.

Table of Contents

• Why This Library?
• Features
• Installation
• Usage
  • Basic Usage
  • Using the Hook
  • Custom Warning Dialog
• Inactivity Detection
• API
  • SessionTimeoutProvider Props
  • useSessionTimeout Hook
• How It Works
  • Implementation Example
  • Key Features
• Use Cases
• Demo
• Tips
• License

Why This Library?

This library detects user inactivity and manages session expiration for security and compliance needs.

Perfect for:

• 🏦 Banking/Finance Apps - Auto-logout after inactivity (PCI-DSS, SOC2)
• 🏢 Enterprise Apps - Security policies requiring session timeouts
• 🛒 E-commerce - Expire shopping carts/sessions
• 🏥 Healthcare Apps - HIPAA compliance with automatic session termination
• 🔐 Any app requiring security-based session management

Features

✅ Inactivity & Idle Detection - Automatically tracks user activity (taps, scrolls, swipes, gestures)
✅ Android 10+ Compatible - No background timer issues
✅ Automatic Lifecycle Handling - Properly handles app background/foreground transitions
✅ Built-in Warning Dialogs - Countdown timer with customizable warning UI
✅ TypeScript Support - Full type definitions included
✅ Zero Native Linking - Works with autolinking
✅ Customizable - Configure timeout duration, warning time, and callbacks
✅ Performant - Uses native modules for accurate timekeeping

Installation

npm install react-native-session-timeout
# or
yarn add react-native-session-timeout

iOS

cd ios && pod install

Usage

Basic Usage

import React from 'react';
import { View, Text } from 'react-native';
import {
  SessionTimeoutProvider,
  useSessionTimeout,
} from 'react-native-session-timeout';

function App() {
  return (
    <SessionTimeoutProvider
      timeout={300000} // 5 minutes in milliseconds
      warningDuration={60000} // Show warning 1 minute before timeout
      onTimeout={() => {
        console.log('Session timed out!');
        // Handle logout or session expiry
      }}
      onWarning={(remainingTime) => {
        console.log(`Warning: ${remainingTime}ms remaining`);
      }}
    >
      <YourApp />
    </SessionTimeoutProvider>
  );
}

Using the Hook

import { useSessionTimeout } from 'react-native-session-timeout';

function YourComponent() {
  const { isWarning, remainingTime, resetTimer, pauseTimer, resumeTimer } =
    useSessionTimeout();

  return (
    <View>
      {isWarning && (
        <View style={styles.warningBanner}>
          <Text>
            Session expiring in {Math.floor(remainingTime / 1000)} seconds
          </Text>
          <Button title="Stay Logged In" onPress={resetTimer} />
        </View>
      )}
      <YourContent />
    </View>
  );
}

Custom Warning Dialog

import React from 'react';
import { Modal, View, Text, Button } from 'react-native';
import {
  SessionTimeoutProvider,
  useSessionTimeout,
} from 'react-native-session-timeout';

function CustomWarningDialog() {
  const { isWarning, remainingTime, resetTimer } = useSessionTimeout();

  return (
    <Modal visible={isWarning} transparent animationType="fade">
      <View style={styles.overlay}>
        <View style={styles.dialog}>
          <Text style={styles.title}>Session Expiring</Text>
          <Text style={styles.message}>
            Your session will expire in {Math.floor(remainingTime / 1000)}{' '}
            seconds
          </Text>
          <Button title="Continue Session" onPress={resetTimer} />
        </View>
      </View>
    </Modal>
  );
}

function App() {
  return (
    <SessionTimeoutProvider
      timeout={300000}
      warningDuration={60000}
      onTimeout={handleTimeout}
    >
      <YourApp />
      <CustomWarningDialog />
    </SessionTimeoutProvider>
  );
}

Inactivity Detection

The library automatically detects user activity and resets the timer on any interaction:

• ✅ Taps - Any touch on the screen
• ✅ Scrolls - ScrollView, FlatList, etc.
• ✅ Swipes - Gesture-based navigation
• ✅ Gestures - Any PanResponder-based interaction

How it works: The library wraps your app with a PanResponder that detects all touch events. When the user interacts with the app, the inactivity timer automatically resets, keeping the session alive. If the user is idle (no interaction) for the configured timeout duration, the onTimeout callback is triggered.

Example Use Case:

// Logout user after 5 minutes of inactivity
<SessionTimeoutProvider
  timeout={300000} // 5 minutes
  onTimeout={() => {
    console.log('User has been idle for 5 minutes');
    // Perform logout
  }}
>
  <YourApp />
</SessionTimeoutProvider>

API

SessionTimeoutProvider Props

Prop	Type	Required	Description
timeout	number	Yes	Total timeout duration in milliseconds
warningDuration	number	No	Show warning this many milliseconds before timeout (default: 60000)
onTimeout	() => void	Yes	Callback when session times out
onWarning	(remainingTime: number) => void	No	Callback when warning period starts
enabled	boolean	No	Enable/disable the timeout (default: true)
pauseOnBackground	boolean	No	Pause timer when app goes to background (default: false)

useSessionTimeout Hook

Returns an object with:

Property	Type	Description
isWarning	boolean	Whether in warning period
remainingTime	number	Milliseconds remaining until timeout
resetTimer	() => void	Reset the session timer
pauseTimer	() => void	Pause the timer
resumeTimer	() => void	Resume the timer
isActive	boolean	Whether timer is currently active

How It Works

The library uses native timers (Android/iOS) for accurate timekeeping and automatically calls your onTimeout callback when the session expires.

Implementation Example

import AsyncStorage from '@react-native-async-storage/async-storage';
import { SessionTimeoutProvider } from 'react-native-session-timeout';

function App() {
  const handleTimeout = async () => {
    try {
      // 1. Call logout endpoint to invalidate server session
      const token = await AsyncStorage.getItem('authToken');
      await fetch('https://api.example.com/logout', {
        method: 'POST',
        headers: { Authorization: `Bearer ${token}` },
      });
    } catch (error) {
      console.error('Logout API error:', error);
      // Continue with local cleanup even if API fails
    }

    // 2. Clear local storage
    await AsyncStorage.removeItem('authToken');

    // 3. Navigate to login
    navigation.reset({ index: 0, routes: [{ name: 'Login' }] });

    // 4. Notify user
    Alert.alert('Session Expired', 'Please log in again');
  };

  return (
    <SessionTimeoutProvider
      timeout={300000} // 5 minutes
      warningDuration={60000} // 1 minute warning
      onTimeout={handleTimeout}
    >
      <YourApp />
    </SessionTimeoutProvider>
  );
}

Key Features

• Native Timers: Accurate timing even when JS thread is busy
• Automatic Lifecycle Handling: Manages app background/foreground transitions
• Warning System: Configurable warning period before timeout
• Activity Tracking: Resets timer on user interaction

Use Cases

This library is essential for apps that require automatic logout for security:

• 🏦 Banking & Finance - PCI-DSS compliance requirement
• 🏥 Healthcare - HIPAA compliance for patient data protection
• 💼 Enterprise - Corporate security policies (ISO 27001)
• 🏛️ Government - Classified/sensitive information handling
• 🔐 Security-sensitive apps - Auto-logout after inactivity

Demo

Tips

Preventing Unwanted Timer Resets

By default, any touch or gesture anywhere in your app will reset the inactivity timer, thanks to the global PanResponder. If you have UI elements (like control buttons, modals, or overlays) that should NOT reset the timer when interacted with, wrap them in a View with onStartShouldSetResponder={() => true}. This prevents touch events from bubbling up to the SessionTimeoutProvider's PanResponder.

Example:

<View onStartShouldSetResponder={() => true}>
  <TouchableOpacity onPress={pauseTimer}>
    <Text>Pause Timer</Text>
  </TouchableOpacity>
</View>

This ensures that only intended interactions reset the timer, while controls and overlays behave as expected.

License

MIT