@tabbridge/use-multi-tab-detection

A lightweight React hook for detecting when your application is open in multiple browser tabs.

Features

• ✅ Native BroadcastChannel API for efficient inter-tab communication
• ✅ Fully type-safe with strict TypeScript
• ✅ Automatic cleanup of inactive tabs
• ✅ Configurable heartbeat intervals and thresholds
• ✅ Callback support for state changes
• ✅ Browser support detection
• ✅ Zero dependencies (except React peer dependency)

Installation

npm install @tabbridge/use-multi-tab-detection

Quick Start

import { useMultiTabDetection } from '@tabbridge/use-multi-tab-detection';

function App() {
  const { isMultiTab, tabCount } = useMultiTabDetection({
    channelName: 'my-app'
  });

  if (isMultiTab) {
    return <div>⚠️ Warning: This app is open in {tabCount} tabs</div>;
  }

  return <div>Your app content</div>;
}

Usage

Basic Implementation

Add the hook to your root layout or any component where you want to track multiple tabs:

import { useMultiTabDetection } from '@tabbridge/use-multi-tab-detection';

export default function Layout() {
  const { isMultiTab, tabCount, tabId } = useMultiTabDetection({
    channelName: 'my-app-channel',
    debug: process.env.NODE_ENV === 'development'
  });

  return (
    <div>
      {isMultiTab && (
        <div className='warning-banner'>
          Multiple tabs detected ({tabCount} active)
        </div>
      )}
      {/* Your app content */}
    </div>
  );
}

With Callbacks

React to multi-tab state changes with the onMultiTabChange callback:

const { isMultiTab, tabCount, activeTabUrls } = useMultiTabDetection({
  channelName: 'my-app',
  onMultiTabChange: (isMultiTab, count, urls) => {
    console.log(`Multi-tab: ${isMultiTab}, Count: ${count}`);
    console.log('Active URLs:', Array.from(urls.values()));

    // Send analytics event
    if (isMultiTab) {
      analytics.track('multi_tab_detected', { tabCount: count });
    }
  }
});

API Reference

useMultiTabDetection(options?)

Options

Option	Type	Default	Description
channelName	string	Required	Unique identifier for the BroadcastChannel
heartbeatInterval	number	10000	Interval (ms) between heartbeat messages
inactivityThreshold	number	30000	Time (ms) before considering a tab inactive
debug	boolean	false	Enable console logging for debugging
onMultiTabChange	function	undefined	Callback when multi-tab state changes

onMultiTabChange Callback

(isMultiTab: boolean, tabCount: number, activeTabUrls: Map<string, string>) => void

Return Value

Property	Type	Description
isMultiTab	boolean	Whether multiple tabs are currently detected
tabCount	number	Total count of active tabs
tabId	string	Unique identifier for the current tab
isSupported	boolean	Whether BroadcastChannel API is supported
activeTabUrls	Map<string, string>	Map of tab IDs to their URLs

How It Works

1. Tab Registration: Each tab creates a unique ID and joins a BroadcastChannel
2. Heartbeat System: Tabs send periodic heartbeat messages to announce they're active
3. Tab Discovery: New tabs broadcast a discovery message, and existing tabs respond
4. Inactive Cleanup: Tabs that haven't sent a heartbeat within the threshold are removed
5. State Updates: The hook tracks active tabs and updates state accordingly

Tab 1                    Tab 2
  |                        |
  |--[heartbeat]---------->|
  |<-------[heartbeat]-----|
  |                        |
  |--[heartbeat]---------->|
  |                        X (closed)
  |
  |--[cleanup after 30s]-->
  | (detects Tab 2 inactive)

Browser Support

Uses the BroadcastChannel API:

• ✅ Chrome 54+
• ✅ Firefox 38+
• ✅ Safari 15.4+
• ✅ Edge 79+
• ❌ Internet Explorer (not supported)

The hook gracefully handles unsupported browsers by setting isSupported: false.

Examples

Analytics Tracking

useMultiTabDetection({
  channelName: 'reporting-demo',
  onMultiTabChange: async (isMultiTab, count, urls) => {
    if (isMultiTab) {
      await fetch('/api/report-multi-tab', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          tabCount: count,
          urls: Array.from(urls.values())
        })
      });
    }
  }
});

Custom Warning Banner

function WarningBanner() {
  const { isMultiTab, tabCount } = useMultiTabDetection({
    channelName: 'banner-demo'
  });

  if (!isMultiTab) return null;

  return (
    <div className='bg-yellow-100 border-l-4 border-yellow-500 p-4'>
      <p className='font-bold'>⚠️ Multiple Tabs Detected</p>
      <p>
        You have {tabCount} tabs open. Please close extra tabs to avoid
        synchronization issues.
      </p>
    </div>
  );
}

Testing

Manual Testing

1. Open your app in one tab with debug: true enabled
2. Open the same page in a second tab
3. Check the browser console for debug messages
4. Verify isMultiTab becomes true and tabCount shows 2
5. Close one tab and verify the count decreases after the inactivity threshold

Troubleshooting

Hook not detecting other tabs

• Ensure all tabs use the same channelName
• Verify isSupported is true in your browser
• Enable debug: true to see message flow in console
• Check browser console for errors

False positives (detecting closed tabs)

• Increase inactivityThreshold if you have slow network conditions
• Default 30s threshold should work for most cases
• Verify cleanup is running with debug: true

Performance concerns

• Default settings are already optimized for most use cases
• Increase heartbeatInterval to reduce message frequency if needed
• Avoid triggering expensive operations in onMultiTabChange callback
• Consider debouncing state updates that cause re-renders

Performance Notes

⚠️ Important: While BroadcastChannel is lightweight, be mindful of:

• Triggering global context updates on every state change
• Re-rendering expensive components unnecessarily
• Triggering data refetches in the callback

Best practices:

• Use onMultiTabChange for side effects (analytics, logging)
• Memoize expensive computations based on isMultiTab
• Debounce UI updates if needed

Security Considerations

• BroadcastChannel only communicates within the same origin (browser security)
• Messages cannot be accessed across different domains
• Tab IDs are randomly generated and not tied to user identity
• Avoid sending sensitive data through the channel

Why BroadcastChannel?

We chose BroadcastChannel over alternatives for several reasons:

Approach	Pros	Cons
BroadcastChannel	✅ Native API ✅ No polling ✅ Auto cleanup	❌ Limited browser support
LocalStorage events	✅ Wider support	❌ Same-origin only ❌ No auto cleanup
SharedWorker	✅ Powerful	❌ Complex setup ❌ Limited support
Server polling	✅ Works everywhere	❌ Network overhead ❌ Requires backend

TypeScript

This package is written in TypeScript and includes full type definitions:

interface UseMultiTabDetectionOptions {
  channelName: string;
  heartbeatInterval?: number;
  inactivityThreshold?: number;
  debug?: boolean;
  onMultiTabChange?: (
    isMultiTab: boolean,
    tabCount: number,
    activeTabUrls: Map<string, string>
  ) => void;
}

interface UseMultiTabDetectionResult {
  isMultiTab: boolean;
  tabCount: number;
  tabId: string;
  isSupported: boolean;
  activeTabUrls: Map<string, string>;
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © TabBridge https://github.com/tabbridge

Links

• npm package
• GitHub repository
• Report issues

---

Made with ❤️ by the TabBridge team