Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Track which tabs are visible and most-recently-used.
Branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


Building Javascript applications that run across multiple browser tabs can be tricky:

  1. Which browser tab is visible (if any)? You may want to do less work if you know that your current tab is not visible anyway.
  2. Which browser tab is primary? You may not want all tabs to process a server side event at the same time. For example, you would not want all of your tabs to generate a "new message" alert or sound.

BrowserTab encapsulates all of this behavior into a simple API:

  • BrowserTab.hidden() true when the current tab is hidden from the visitor
  • BrowserTab.primary() true when the current tab is the most-recently-used tab


In the browser, just include the module with <script src="browsertab.js"></script>. Then you should be able to use the global BrowserTab object:

if (BrowserTab.hidden()) {
  // This tab is not visible, maybe you can stop requesting data from the server

if (BrowserTab.primary()) {
  // This tab is primary, should be okay to trigger things like sounds from this one

You can also listen for changes to hidden/primary state:

BrowserTab.on("change:hidden", function() {
  // This tab changed from visible to hidden, or vice-versa.

BrowserTab.on("change:primary", function() {
  // This tab changed from primary to non-primary, or vice-versa.

Advanced Usage

You can use BrowserTab in node:

  1. Install the module using npm install browsertab
  2. At the top of your code, var BrowserTab = require("browsertab")
  3. Create a new BrowserTab object, for example: var tab = new BrowserTab({window: jsdom().createWindow()})

In general, you can inject all of the BrowserTab dependencies using the options:

var tab = new BrowserTab({
  window: window, // override window (helpful when mocking in unit tests)
  document: document, // override document (helpful when mocking in unit tests)
  localStorage: localStorage, // override localStorage (helpful when mocking in unit tests)
  storageNamespace: "_BrowserTabStorageNamespace" // change storage namespace for coordinating "primary" tab


Found a bug? Have a new idea? Fork away and send us a pull request! Or call us, maybe?

Something went wrong with that request. Please try again.