DetectTab API Documentation

npm install detect-tab

yarn add detect-tab

pnpm add detect-tab

import { DetectTab } from 'detect-tab';

// Create instance
const detector = new DetectTab();

// Check current state
console.log('Is visible:', detector.isVisible());
console.log('Is focused:', detector.isFocused());

// Listen for changes
detector.onStateChange((state, info) => {
    if (state === 'hidden') {
        pauseAnimations();
    } else {
        resumeAnimations();
    }
});

// Listen for focus changes
detector.onFocusChange((focused, info) => {
    console.log('Tab focused:', focused);
});

const detector = new DetectTab({
    persistent: true,     // Save data across sessions
    debounceTime: 250,   // Wait 250ms before firing events
    debug: true          // Enable debugging
});

import { TabEvent } from 'detect-tab';

detector.on(TabEvent.VISIBILITY_CHANGE, (info) => {
    console.log('Visibility changed:', info.visible);
});

detector.on(TabEvent.FOCUS, (info) => {
    console.log('Tab gained focus');
});

detector.on(TabEvent.BLUR, (info) => {
    console.log('Tab lost focus');
});

interface TabInfo {
    visible: boolean;           // Current visibility state
    focused: boolean;           // Current focus state
    state: TabState;           // Current tab state enum
    lastStateChange: number;   // Timestamp of last state change
    visibilityChanges: number; // Total number of visibility changes
    focusChanges: number;      // Total number of focus changes
    timeInCurrentState: string; // Formatted time in current state
    totalVisibleTime: number;   // Total time visible (milliseconds)
    totalHiddenTime: number;    // Total time hidden (milliseconds)
}

interface TimeStats {
    totalVisibleTime: string;   // Formatted total visible time
    totalHiddenTime: string;    // Formatted total hidden time
    timeInCurrentState: string; // Formatted current state time
    totalTime: string;          // Formatted total session time
}

enum TabState {
    VISIBLE = 'visible',
    HIDDEN = 'hidden'
}

const detector = new DetectTab();

detector.onStateChange((state) => {
    if (state === 'hidden') {
        // Pause animations
        clearInterval(animationTimer);
        
        // Reduce network requests
        clearInterval(dataUpdateTimer);
        dataUpdateTimer = setInterval(updateData, 30000); // 30s instead of 1s
        
        // Pause videos
        document.querySelectorAll('video').forEach(v => v.pause());
    } else {
        // Resume normal operations
        startAnimations();
        clearInterval(dataUpdateTimer);
        dataUpdateTimer = setInterval(updateData, 1000); // Back to 1s
        document.querySelectorAll('video').forEach(v => v.play());
    }
});

detector.onStateChange((state, info) => {
    analytics.track('tab_visibility_change', {
        visible: info.visible,
        timeInState: info.timeInCurrentState,
        totalChanges: info.visibilityChanges,
        sessionTime: info.totalVisibleTime + info.totalHiddenTime
    });
});

// Track session duration on page unload
window.addEventListener('beforeunload', () => {
    const stats = detector.getTimeStats();
    analytics.track('session_end', {
        visibleTime: stats.totalVisibleTime,
        hiddenTime: stats.totalHiddenTime,
        totalTime: stats.totalTime
    });
});

let notificationCount = 0;
const originalTitle = document.title;

detector.onFocusChange((focused) => {
    if (focused) {
        // Clear notification badge when user returns
        document.title = originalTitle;
        notificationCount = 0;
    }
});

// Show notification count when hidden
function onNewMessage(message) {
    if (!detector.isVisible()) {
        notificationCount++;
        document.title = `(${notificationCount}) ${originalTitle}`;
        
        // Show browser notification
        if (Notification.permission === 'granted') {
            new Notification('New Message', {
                body: message.text,
                icon: '/favicon.ico'
            });
        }
    }
}

// Enable debug mode to see what's happening
const detector = new DetectTab({ debug: true });

// Check if detection is active
if (!detector.isActive()) {
    detector.start();
}

// Verify browser support
if (!document.hidden !== undefined) {
    console.warn('Page Visibility API not supported');
}

// Always destroy instances when done
window.addEventListener('beforeunload', () => {
    detector.destroy();
});

// In React components
useEffect(() => {
    const detector = new DetectTab();
    
    return () => {
        detector.destroy(); // Cleanup on unmount
    };
}, []);

// Import types explicitly
import { 
    DetectTab, 
    TabInfo, 
    TabState, 
    DetectTabOptions 
} from 'detect-tab';

// Use proper typing
const options: DetectTabOptions = {
    persistent: true,
    debug: false
};

const detector = new DetectTab(options);