tabs

The tabs module provides easy access to tabs and tab-related events.

The module itself can be used like a basic list of all opened tabs across all windows. In particular, you can enumerate it:

var tabs = require('tabs');
for each (var tab in tabs)
  console.log(tab.title);

You can also access individual tabs by index:

var tabs = require('tabs');

tabs.on('ready', function () {
  console.log('first: ' + tabs[0].title);
  console.log('last: ' + tabs[tabs.length-1].title);
});

You can open a new tab, specifying various properties including location:

var tabs = require("tabs");
tabs.open("http://www.example.com");

You can register event listeners to be notified when tabs open, close, finish loading DOM content, or are made active or inactive:

var tabs = require("tabs");

// Listen for tab openings.
tabs.on('open', function onOpen(tab) {
  myOpenTabs.push(tab);
});

// Listen for tab content loads.
tabs.on('ready', function(tab) {
  console.log('tab is loaded', tab.title, tab.url)
});

You can get and set various properties of tabs (but note that properties relating to the tab's content, such as the URL, will not contain valid values until after the tab's ready event fires). By setting the url property you can load a new page in the tab:

var tabs = require("tabs");
tabs.on('activate', function(tab) {
  tab.url = "http://www.example.com";
});

You can attach a content script to the page hosted in a tab, and use that to access and manipulate the page's content:

var tabs = require("tabs");

tabs.on('activate', function(tab) {
  tab.attach({
    contentScript: 'self.postMessage(document.body.innerHTML);',
    onMessage: function (message) {
      console.log(message);
    }
  });
});

API Reference

Classes

Tab

A Tab instance represents a single open tab. It contains various tab properties, several methods for manipulation, as well as per-tab event registration.

Tabs emit all the events described in the Events section. Listeners are passed the Tab object that triggered the event.

Methods
pin()

Pins this tab as an app tab.

unpin()

Unpins this tab.

close(callback)

Closes this tab.

[ callback : function ]

A function to be called when the tab finishes its closing process. This is an optional argument.

reload()

Reloads this tab.

activate()

Makes this tab active, which will bring this tab to the foreground.

attach(options)

Create a page mod and attach it to the document in the tab.

Example

var tabs = require("tabs");

tabs.on('ready', function(tab) {
  tab.attach({
      contentScript:
        'document.body.style.border = "5px solid red";'
  });
});
options : object

Options for the page mod, with the following keys:

[ contentScriptFile : string,array ]

The local file URLs of content scripts to load. Content scripts specified by this option are loaded before those specified by the contentScript option. Optional.

[ contentScript : string,array ]

The texts of content scripts to load. Content scripts specified by this option are loaded after those specified by the contentScriptFile option. Optional.

[ onMessage : function ]

A function called when the page mod receives a message from content scripts. Listeners are passed a single argument, the message posted from the content script. Optional.

Returns: Worker

See Content Scripts guide to learn how to use the Worker object to communicate with the content script.

Properties
title : string

The title of the page currently loaded in the tab. This property can be set to change the tab title.

url : String

The URL of the page currently loaded in the tab. This property can be set to load a different URL in the tab.

favicon : string

The URL of the favicon for the page currently loaded in the tab. This property is read-only.

index : integer

The index of the tab relative to other tabs in the application window. This property can be set to change its relative position.

isPinned : boolean

Whether or not tab is pinned as an app tab. This property is read-only.

getThumbnail : method

Returns thumbnail data URI of the page currently loaded in this tab.

Events
close

This event is emitted when the tab is closed. It's also emitted when the tab's window is closed.

Tab

Listeners are passed the tab object.

ready

This event is emitted when the DOM for the tab's content is ready. It is equivalent to the DOMContentLoaded event for the given content page.

A single tab will emit this event every time the DOM is loaded: so it will be emitted again if the tab's location changes or the content is reloaded.

After this event has been emitted, all properties relating to the tab's content can be used.

Tab

Listeners are passed the tab object.

activate

This event is emitted when the tab is made active.

Tab

Listeners are passed the tab object.

deactivate

This event is emitted when the tab is made inactive.

Tab

Listeners are passed the tab object.

Functions

open(options)

Opens a new tab. The new tab will open in the active window or in a new window, depending on the inNewWindow option.

Example

var tabs = require("tabs");

// Open a new tab on active window and make tab active.
tabs.open("http://www.mysite.com");

// Open a new tab in a new window and make it active.
tabs.open({
  url: "http://www.mysite.com",
  inNewWindow: true
});

// Open a new tab on active window in the background.
tabs.open({
  url: "http://www.mysite.com",
  inBackground: true
});

// Open a new tab as an app tab and do something once it's open.
tabs.open({
  url: "http://www.mysite.com",
  isPinned: true,
  onOpen: function onOpen(tab) {
    // do stuff like listen for content
    // loading.
  }
});
options : object

An object containing configurable options for how and where the tab will be opened, as well as a listeners for the tab events.

If the only option being used is url, then a bare string URL can be passed to open instead of adding at a property of the options object.

[ url : string ]

String URL to be opened in the new tab. This is a required property.

[ inNewWindow : boolean ]

If present and true, a new browser window will be opened and the URL will be opened in the first tab in that window. This is an optional property.

[ inBackground : boolean ]

If present and true, the new tab will be opened to the right of the active tab and will not be active. This is an optional property.

[ isPinned : boolean ]

If present and true, then the new tab will be pinned as an app tab.

[ onOpen : function ]

A callback function that will be registered for 'open' event. This is an optional property.

[ onClose : function ]

A callback function that will be registered for 'close' event. This is an optional property.

[ onReady : function ]

A callback function that will be registered for 'ready' event. This is an optional property.

[ onActivate : function ]

A callback function that will be registered for 'activate' event. This is an optional property.

[ onDeactivate : function ]

A callback function that will be registered for 'deactivate' event. This is an optional property.

Properties

activeTab : Tab

The currently active tab in the active window. This property is read-only. To activate a Tab object, call its activate method.

Example

// Get the active tab's title.
var tabs = require("tabs");
console.log("title of active tab is " + tabs.activeTab.title);

length : number

The number of open tabs across all windows.

Events

open

This event is emitted when a new tab is opened. This does not mean that the content has loaded, only that the browser tab itself is fully visible to the user.

Properties relating to the tab's content (for example: title, favicon, and url) will not be correct at this point. If you need to access these properties, listen for the ready event:

var tabs = require("tabs");
tabs.on('open', function(tab){
  tab.on('ready', function(tab){
    console.log(tab.url);
  });
});
Tab

Listeners are passed the tab object that just opened.

close

This event is emitted when a tab is closed. When a window is closed this event will be emitted for each of the open tabs in that window.

Tab

Listeners are passed the tab object that has closed.

ready

This event is emitted when the DOM for a tab's content is ready. It is equivalent to the DOMContentLoaded event for the given content page.

A single tab will emit this event every time the DOM is loaded: so it will be emitted again if the tab's location changes or the content is reloaded.

After this event has been emitted, all properties relating to the tab's content can be used.

Tab

Listeners are passed the tab object that has loaded.

activate

This event is emitted when an inactive tab is made active.

Tab

Listeners are passed the tab object that has become active.

deactivate

This event is emitted when the active tab is made inactive.

Tab

Listeners are passed the tab object that has become inactive.