Chrome Tabs jQuery Wrapper

This documents the jQuery wrapper around Chrome Tabs, covering both Electron Webviews and also Web Browser IFrames; i.e., the same documentation applies to both use cases, with just a couple of exceptions noted in this article.

jQuery Activation Example

This activates Chrome Tabs on an HTML element:

<div class="chrome-tabs"></div>
$('.chrome-tabs').chromeTabs();

↑↓ These two snippets do the exact same thing.

Why? Because what you see below are the default option values. In other words, if you omit all of the option values, this is the way Chrome Tabs will behave by default. So these two snippets are equivalent. Of course, you can change the default option values to whatever works best for you.

$('.chrome-tabs').chromeTabs({
  minWidth: 45,
  maxWidth: 243,

  leftPadding: 0,
  leftPaddingMobile: 0,

  rightPadding: 300,
  rightPaddingMobile: 45,

  overlapDistance: 14,

  views: 'iframes',
  // `iframes` or `webviews`.
  // `webviews` = Electron compatibility.
  // Or leave empty to disable views entirely.

  allowDragNDrop: true,
  allowDoubleClick: true,
  initial: [], // Initial tabs.
  // This is an array of prop objs.

  defaultProps: {
    title: 'New Tab',
    favicon: 'default',
    url: 'https://duckduckgo.com/?kae=b&kak=-1&kao=-1&k1=-1&kt=p&kj=f5f5f5&ka=p&kf=1&kam=google-maps&km=l&ko=1',

    unknownUrlTitle: 'Web Page',
    loadingFavicon: 'loading',

    allowClose: true,

    viewAttrs: {}
  },
});

jQuery Config. Options

minWidth: 45

The minimum width of each tab, in pixels. When new tabs are added, or when a window is resized, the width of each tab changes automatically. This setting controls the absolute minimum width allowed for each tab.

maxWidth: 243

The maximum width of each tab, in pixels. When old tabs are removed, or when a window is resized, the width of each tab changes automatically. This setting controls the absolute maximum width allowed for each tab.

leftPadding: 0

Padding on the left-hand side of the entire tab group, in pixels. The default value is 0. In Electron apps you might want to use leftPadding: 60 to allow room for window minimize/maximize controls in inset window frames on macOS. It just depends on how you setup your Electron app.

leftPaddingMobile: 0

Padding on the left-hand side of the entire tab group, in pixels, whenever the viewport width is <= 767px. In Electron apps you might want to use leftPaddingMobile: 60 to allow room for window minimize/maximize controls in inset window frames on macOS. It just depends on how you setup your Electron app.

rightPadding: 300

Padding on the right-hand side of the entire tab group, in pixels. The default value gives you room to add your own custom UI elements that sit inside the tabbed interface, and your custom UI elements will have 300 pixels of space that they can consume; i.e., without being covered up by a long list of tabs created by an end-user.

rightPaddingMobile: 45

Padding on the right-hand side of the entire tab group, in pixels, whenever the viewport width is <= 767px. The default value of 45 assumes that you’ll hide whatever custom UI element you were showing on the right-hand side, and replace that with a hamburger icon menu, for which you’ll have 45 pixels of space.

overlapDistance: 14

This is the amount of tab overlap, in pixels. Each tab overlaps the previous tab by this number of pixels in order to mimic Google Chrome’s interface design.

views: 'iframes'

This controls the underlying Chrome Tab Views class. In short, ‘Views’ make ‘Tabs’ function like they would in a typical web browser. When Views are enabled, a tab is associated with a url: property.

  • 'iframes' If you set this to iframes, when a tab is selected, the url: tab property is loaded automatically in an <iframe>. This makes Chrome Tabs compatible with regular web browsers.

  • 'webviews' In Electron, you can set this to webviews. When a tab is selected, the url: tab property is loaded in a <webview> tag automatically. The <webview> tag only works in Electron apps.

  • '' If you set this to an empty string, all you get are the tabs; i.e., you can attach your own event handlers that load whatever content is associated with a given tab; e.g., via AJAX, custom iframes, etc.

allowDragNDrop: true

By default, tabs can be arranged by dragging them around and dropping them into a desired location. If you’d like to disable this functionality, set this option to false; i.e., false = do not allow the end-user to arrange tabs.

allowDoubleClick: true

By default, double-clicking the tabbed interface will add a new default tab. If you’d like to disable this functionality, set this option to false; i.e., false = do not allow the end-user to create new tabs on their own.

initial: []

To begin with a specific set of tabs, you can add an array of objects (Tab Properties). One for each tab you want to initialize.

For any given tab, any properties you don’t set will automatically inherit from the list of defaultProps: {}, which is also a configurable option.

initial: [
  {}, // i.e., Default tab w/ no overriding properties.

  { url: '1.html' },
  { url: '2.html' },
  { url: '3.html' },
  { url: '4.html' },
  { url: '5.html' },
  { url: '6.html' },
  { url: '7.html' },
  { url: '8.html' },
  { url: '9.html' },

  {
    title: 'New Tab',
    favicon: 'src/images/default-favicon.svg',
    url: 'https://duckduckgo.com/?kae=b&kak=-1&kao=-1&k1=-1&kt=p&kj=f5f5f5&ka=p&kf=1&kam=google-maps&km=l&ko=1',
  }
]

Warning: Don’t use the initial: [] option if you’re attaching custom event handlers. ‘initial’ tabs won’t trigger custom event handlers. Simply because initial tabs are initialized together as the class is constructed; i.e., before you’ve attached custom event handlers.

If you’re attaching custom event handlers, use the addTabs() method instead; i.e., add your initial tabs after your custom event handlers have been attached, which allows custom event handlers to work as intended.

defaultProps: {}

This is a set of default Tab Properties that each new tab will inherit from. By configuring default properties, you establish traits that every new tab will have by default, and then you can override these defaults when new tabs are being added. In short, this saves you from repeating yourself. This also establishes what a new tab will look like whenever a user double-clicks the tabbed interface.

defaultProps: {
  title: 'New Tab',
  favicon: 'src/images/default-favicon.svg',
  url: 'https://duckduckgo.com/?kae=b&kak=-1&kao=-1&k1=-1&kt=p&kj=f5f5f5&ka=p&kf=1&kam=google-maps&km=l&ko=1',

  unknownUrlTitle: 'Web Page',
  loadingFavicon: 'src/images/loading-favicon.gif',

  allowClose: true,

  viewAttrs: {}
}

Notable Exception: When a tab is given a url: property, its favicon: and title: do not inherit any defaults. Even setting title: or favicon: properties explicitly will have little impact. Instead, the favicon & title are automatically derived from the URL itself, as one would expect from a browser.

On the other hand, if you’re using views: 'iframes', and you attempt to add a tab with a URL that is not on the same domain as your tabbed interface, browser security restrictions do not allow for automatic detection. In such a case, explicit favicon: and title: properties must be set for each tab. Note also, this does not apply to Electron <webview> tags, which are not subjected to the same cross-domain limitations as <iframe> tags.

Individual Tab Properties

title: 'New Tab',
favicon: 'src/images/default-favicon.svg',
url: 'https://duckduckgo.com/?kae=b&kak=-1&kao=-1&k1=-1&kt=p&kj=f5f5f5&ka=p&kf=1&kam=google-maps&km=l&ko=1',

unknownUrlTitle: 'Web Page',
loadingFavicon: 'src/images/loading-favicon.gif',

allowClose: true,

viewAttrs: {}
title: ''

Establishes the default title for a tab.

favicon: 'default'

Establishes the favicon for a tab. This can be the special string: default (built-in default tab icon), a data: URI, a relative image path (svg,png,gif,ico), or a full URL leading to an image. The default value (default) works well in both the light & dark themes.

url: ''

This establishes the content for the tab ‘view’; i.e., the location of the content that should be displayed whenever the tab is active.

Note: When a tab is given a url: property, its favicon: and title: properties do not inherit any defaults. Even setting the title: or favicon: properties explicitly will have little impact. Instead, the favicon & title are derived from the URL itself, as one would expect from a browser.

On the other hand, if you’re using views: 'iframes', and you attempt to add a tab with a URL that is not on the same domain as your tabbed interface, browser security restrictions do not allow for automatic detection. In such a case, explicit favicon: and title: properties must be set for each tab. Note also, this does not apply to Electron <webview> tags, which are not subjected to the same cross-domain limitations as <iframe> tags.

unknownUrlTitle: ''

In the case of loading failure, or when cross-domain restrictions prohibit automatic title detection, this default title will be displayed instead.

loadingFavicon: 'loading'

Establishes the loading favicon. This can be the special string: loading (built-in loading icon), a data: URI, a relative image path (svg,png,gif,ico), or a full URL leading to an image. The built-in default value (loading) is recommended, which helps to convey that a tab is loading in both the light & dark themes.

allowClose: true

Should an end-user be allowed to close the tab? If false, the close icon will not be shown, making it impossible to close the tab.

viewAttrs: {}

A ‘view’ is the underlying <iframe> or <webview> tag. If you’d like to set HTML attributes on the auto-generated view for any given tab, you can use this property to do that. These are simply key: value pairs representing HTML attrs. Here is an example of some attributes supported by the <webview> tag in Electron apps.

viewAttrs: {
  preload: './my.js',
  allowpopups: null,
  disablewebsecurity: null,
  webpreferences: 'allowDisplayingInsecureContent'
  // ... and some others are also available.
  // See: <http://electron.atom.io/docs/api/web-view-tag/>
}

Class Properties

Underlying Class Instance via jQuery

The class instance can be obtained via jQuery.
You can point $chromeTabs._ to the underlying class instance.

// References we'll work with below.
var $chromeTabs = $('.chrome-tabs').chromeTabs(); // w/ jQuery wrapper.
$chromeTabs._ = $chromeTabs.data('chromeTabs'); // ChromeTabs class instance.

$tabs

A jQuery object representing the current set of tabs.

Note: Tab elements are indexed by jQuery and their index reflects the location of each tab as it appears in the UI. Remember that jQuery uses a zero-based index system. So the first tab (as seen in the UI) would be at index position 0.

var $tabs = $chromeTabs._.$tabs; // All tabs.
var $firstTab = $tabs.eq(0); // First tab w/ jQuery wrapper.
var firstTab = $tabs[0]; // DOM element w/o jQuery wrapper.

$currentTab

A jQuery object representing the current/active tab.

var $tab = $chromeTabs._.$currentTab;

To find a tab’s current index (i.e., position in the interface).

var $tabIndex = $tab.index();

tabWidth

The current width of each tab, in pixels.

var tabWidth = $chromeTabs._.tabWidth;

effectiveTabWidth

The current effective width of each tab, in pixels; i.e., tabWidth minus any overlap that is applied via the configuration option: overlapDistance.

var effectiveTabWidth = $chromeTabs._.effectiveTabWidth;

tabPositions

The current X (left-offset) positions for each tab.

var tabPositions = $chromeTabs._.tabPositions;

settings

The currently configured settings for the ChromeTabs instance.

Note: While not enforced, this should be considered read-only. Please do not change settings after the ChromeTabs instance has already been initialized via jQuery.

var settings = $chromeTabs._.settings;

id

The auto-assigned ID for the ChromeTabs instance; e.g., 0.

Note: This is simply a numeric counter, starting from 0. If there’s more than a single instance of ChromeTabs, each instance will have IDs: 0, 1, 2, 3, etc.

var id = $chromeTabs._.id;

Class Methods

Underlying Class Instance via jQuery

The class instance can be obtained via jQuery.
You can point $chromeTabs._ to the underlying class instance.

// References we'll work with below.
var $chromeTabs = $('.chrome-tabs').chromeTabs(); // w/ jQuery wrapper.
$chromeTabs._ = $chromeTabs.data('chromeTabs'); // ChromeTabs class instance.

addTab()

Parameters
props Object

See: Tab Properties Documentation.

setAsCurrent Boolean

Set the new tab as the current active tab? Default: true.

Returns

A jQuery object representing the new tab object in the DOM.

var $tab = $chromeTabs._.addTab({ url: '1.html' });

addTabIfNotExists()

Parameters
props Object

See: Tab Properties Documentation.

setAsCurrent Boolean

Set as the current active tab? Default: true.

checkProps Object (or undefined)

Properties to check. See: Tab Properties Documentation. If this parameter is passed, the method checks for an existing tab with properties matching these. If this parameter is not passed, or is empty, the method checks for an existing tab with properties matching the props parameter. In other words, if not given, this defaults to the value of props.

Note: checkProps can contain any number of tab properties to check for. You can check for only a matching url:, or you can check for a matching favicon:, title:, and allowClose: property as well — and there are others. It just depends on how specific you’d like to be.

Returns

A jQuery object representing the new (or existing) tab object in the DOM.

var $tab = $chromeTabs._.addTabIfNotExists({ url: '1.html' });

See also: tabExists()

addTabs()

Parameters
propSets Array

e.g., [{}, {}, {}]. See: Tab Properties Documentation.

setAsCurrent Boolean

Set the first new tab as the current active tab? Default: true.

Returns

A jQuery object set representing each new tab object in the DOM.

var $tabs = $chromeTabs._.addTabs([
  { url: '1.html' },
  { url: '2.html' },
  { url: '3.html' },
  {
    title: 'New Tab',
    favicon: 'favicon.png',
    url: 'https://example.com',
  }
]);

removeTab()

Parameters
$tab jQuery

i.e., A jQuery object representing a single tab in the DOM.

Note: If the jQuery object contains more than a single tab, only the first tab will be removed; via $tab.first(). Therefore, you should call removeTab() separately, for each tab you want to remove.

var $tab0 = $('.chrome-tabs .-tab').eq(0);
$chromeTabs._.removeTab($tab0); // Remove first tab (index 0).

removeCurrentTab()

Note: If there is no current/active tab, this fails quietly and does nothing.

$chromeTabs._.removeCurrentTab(); // Removes current/active tab.

removeTabs()

Parameters
$tabs jQuery

i.e., A jQuery object representing a set of tab objects in the DOM.

var $tabs = $('.chrome-tabs .-tab').not('.-current');
$chromeTabs._.removeTabs($tabs); // Remove all except the current tab.

setCurrentTab()

Parameters
$tab jQuery

i.e., A jQuery object representing a single tab in the DOM.

Note: If the jQuery object contains more than a single tab, only the first tab will be set as current; via $tab.first(). Only one tab can be current/active at any given time.

var $tab = $('.chrome-tabs .-tab').eq(2);
$chromeTabs._.setCurrentTab($tab); // Third tab (index 2) is now active.

updateTab()

Parameters
$tab jQuery

i.e., A jQuery object representing a single tab in the DOM.

props Object

Properties to update. See: Tab Properties Documentation.

via String

Optional. This is passed to event callback handlers when the tabUpdated event is triggered as a result of calling this method. In certain scenarios, this can help developers decide whether to respond to the update event, or ignore it.

Note: If the jQuery object contains more than a single tab, only the first tab will be updated; via $tab.first(). If you need to update multiple tabs, build an iteration of your own that updates each tab individually.

var $tab = $('.chrome-tabs .-tab').eq(2);
$chromeTabs._.updateTab($tab, {url: 'http://example.com'});
// Third tab (index 2) changes location.

Another quick example:

var $tab = $('.chrome-tabs .-tab').eq(1);
$chromeTabs._.updateTab($tab, {
  title: 'Currently Loading...',
  favicon: 'src/images/loading-favicon.gif'
}); // Second tab (index 1) gets a new favicon & title.

tabExists()

Parameters
props Object (or undefined)

Properties to check. See: Tab Properties Documentation. If this parameter is passed, the method checks for an existing tab with matching properties. If this parameter is not passed, or is passed explicitly as undefined, the method checks if any tab exists.

props can contain any number of tab properties to check for. You can check for only a matching url:, or you can check for a matching favicon:, title:, and allowClose: property as well — and there are others. It just depends on how specific you’d like to be.

Returns

A jQuery object representing the first matching tab object in the DOM; else false if not exists.

var $existingTab = $chromeTabs._.tabExists({url: 'http://example.com'});
// If a tab with this `url:` already exists, $existingTab is a jQuery object referencing that tab.

See also: addTabIfNotExists()

destroy()

You can use this to cleanup the DOM and do something else.

$chromeTabs._.destroy(); // Destroys events, elements, etc.
$chromeTabs._ = null; // Also kills your own instance reference.
// Killing your own instance reference allows the JavaScript garbage collector to free memory.

jQuery Events

constructed

Triggered whenever the class is first being constructed, but before it has been fully initialized; i.e., all properties are set, but the DOM and event handlers have not yet been initialized.

Callback Parameters
event Object

The event object properties passed by jQuery.

instance ChromeTabs

The associated ChromeTabs class instance.

$chromeTabs.on('constructed', function (event, instance) {
  console.log('Tabs constructed.');
});

initialized

Triggered after the class is constructed and fully initialized.

Callback Parameters
event Object

The event object properties passed by jQuery.

instance ChromeTabs

The associated ChromeTabs class instance.

$chromeTabs.on('initialized', function (event, instance) {
  console.log('Tabs initialized.');
});

destroyed

Triggered when the class is destroyed via destroy().

Callback Parameters
event Object

The event object properties passed by jQuery.

instance ChromeTabs

The associated ChromeTabs class instance.

$chromeTabs.on('destroyed', function (event, instance) {
  console.log('Tabs destroyed.');
});

tabAdded

Triggered after each new tab is added to the DOM, but before its properties have been set. The object will exist in the DOM at this point, but things like favicon:, title:, url:, etc. will not yet be defined.

Callback Parameters
event Object

The event object properties passed by jQuery.

$tab jQuery

A jQuery object representing the new tab in the DOM.

instance ChromeTabs

The associated ChromeTabs class instance.

$chromeTabs.on('tabAdded', function (event, $tab, instance) {
  console.log('Tab added.', $tab);
});

tabUpdated

Triggered when a new tab (or any tab) is updated in some way; e.g., when things like favicon:, title:, url: are set initially or altered later.

Callback Parameters
event Object

The event object properties passed by jQuery.

$tab jQuery

A jQuery object representing the tab in the DOM.

props Object

See: Tab Properties Documentation. This is a full & complete tab properties object representing the current state of the tab; i.e., after the update occurred. Any properties that were not updated, will have already been set to either their original/previous value, or to the default value in accordance with setttings.defaultProps. Again, this represents the current state of the tab in a full & complete way.

via String (or undefined)

This is an optional identifier passed to the underlying updateTab() method. If the original caller defined this variable, it is passed in the event to help listeners recognize who/what originated the call to updateTab(). For example, if you call updateTab() yourself, and you are also listening to the tabUpdated event, you can pass the via parameter to updateTab(), and then look for it in your own listener — choosing to respond or ignore.

prevProps Object

The previous tab properties, before the update. This is either the full & complete tab properties object prior to the update, or an empty object in the case of a new tab having its properties set/updated for the first time.

newProps Object

The new tab properties that were set by this update. This is not a full & complete tab properties object. It will only contain properties that were updated.

instance ChromeTabs

The associated ChromeTabs class instance.

$chromeTabs.on('tabUpdated', function (event, $tab, props, via, prevProps, newProps, instance) {
  console.log('Tab updated.', $tab, props, via, prevProps, newProps);
});

currentTabChanged

Triggered when the current/active tab is changed.

Callback Parameters
event Object

The event object properties passed by jQuery.

$tab jQuery

A jQuery object representing the current/active tab in the DOM.

instance ChromeTabs

The associated ChromeTabs class instance.

$chromeTabs.on('currentTabChanged', function (event, $tab, instance) {
  console.log('Current tab changed to.', $tab);
});

tabDragStarted

Triggered when a tab is being dragged (i.e., first locked onto).

Callback Parameters
event Object

The event object properties passed by jQuery.

$tab jQuery

A jQuery object representing the tab in the DOM.

instance ChromeTabs

The associated ChromeTabs class instance.

$chromeTabs.on('tabDragStarted', function (event, $tab, instance) {
  console.log('Tab drag started.', $tab);
});

tabDragMoved

Triggered when a tab is being dragged into a new location, but before it has been dropped and locked into that new location.

Callback Parameters
event Object

The event object properties passed by jQuery.

$tab jQuery

A jQuery object representing the tab in the DOM.

indexes Object {prevIndex: [Number], newIndex: [Number]}

Indicating both the old and new location of the tab, based on its index position in the DOM. jQuery uses a zero-based index, so a tab that has a newIndex of 0 will be in the first position (first child). You can also determine the current index using $tab.index() — a method provided by jQuery.

instance ChromeTabs

The associated ChromeTabs class instance.

$chromeTabs.on('tabDragMoved', function (event, $tab, indexes, instance) {
  console.log('Tab dragged to a new location.', $tab, indexes);
});

tabDragStopped

Triggered when a tab is dropped and locked into a new location. The location will have already been determined ahead of time and reported via the tabDragMoved event. Therefore, there’s little reason to attach to this event. Generally speaking, it’s better to use tabDragMoved. This tabDragStopped event simply indicates the end-user is done moving things around — nothing more.

Callback Parameters
event Object

The event object properties passed by jQuery.

$tab jQuery

A jQuery object representing the tab in the DOM.

newIndex Number

jQuery uses a zero-based index, so a tab that has a newIndex of 0 will be in the first position (first child). You can also determine the current index using $tab.index() — a method provided by jQuery.

instance ChromeTabs

The associated ChromeTabs class instance.

$chromeTabs.on('tabDragStopped', function (event, $tab, newIndex, instance) {
  console.log('Tab drag stopped.', $tab, newIndex);
});

tabBeingRemoved

Triggered right before a tab is about to be removed from the DOM.

Callback Parameters
event Object

The event object properties passed by jQuery.

$tab jQuery

A jQuery object representing the tab in the DOM.

instance ChromeTabs

The associated ChromeTabs class instance.

$chromeTabs.on('tabBeingRemoved', function (event, $tab, instance) {
  console.log('Tab will be removed.', $tab);
});

tabRemoved

Triggered right after a tab is removed from the DOM.

Callback Parameters
event Object

The event object properties passed by jQuery.

$tab jQuery

A jQuery object representing the tab in the DOM.

instance ChromeTabs

The associated ChromeTabs class instance.

$chromeTabs.on('tabRemoved', function (event, $tab, instance) {
  console.log('Tab removed.', $tab);
});

ChromeTabViews @TODO

There are some other low-level properties, methods, and events associated with Views being altered in response to Tabs being altered. For the most part, these are for internal use only, but eventually I’d like to document everything. For now, here is a quick look at the View events that are available.

Note: ‘Views’ make ‘Tabs’ function like they would in a typical web browser. When Views are enabled, a tab is associated with a url: property. To learn more about Views, see: views: configuration option.

// References we'll work with below.
var $chromeTabs = $('.chrome-tabs').chromeTabs(); // w/ jQuery wrapper.
$chromeTabs._ = $chromeTabs.data('chromeTabs'); // ChromeTabs class instance.

// Additional references we'll work with below.
var $chromeTabViews = $chromeTabs._.$views; // jQuery wrapper for `.chrome-tabs > .-views`.
$chromeTabViews._ = $chromeTabViews.data('chromeTabViews'); // ChromeTabViews class instance.

$chromeTabViews.on('constructed', function (event, instance){ console.log('Views constructed.'); });
$chromeTabViews.on('initialized', function (event, instance){ console.log('Views initialized.'); });
$chromeTabViews.on('destroyed', function (event, instance){ console.log('Views destroyed.'); });

$chromeTabViews.on('viewIndexed', function (event, view, locations, instance){ console.log('View indexed.', view, locations); });
$chromeTabViews.on('viewAdded', function (event, view, instance){ console.log('View added.', view); });
$chromeTabViews.on('viewUpdated', function (event, view, props, via, prevProps, newProps, instance){ console.log('View props updated.', view, props, via, prevProps, newProps); });
$chromeTabViews.on('currentViewChanged', function (event, view, instance){ console.log('Current view changed to.', view); });

$chromeTabViews.on('viewBeingRemoved', function (event, view, instance){ console.log('View will be removed.', view); });
$chromeTabViews.on('viewRemoved', function (event, view, instance){ console.log('View removed.', view); });

$chromeTabViews.on('viewStartedLoading', function (event, view, instance){ console.log('View started loading.', view); });
$chromeTabViews.on('viewFaviconUpdated', function (event, view, favicon, instance){ console.log('View favicon updated.', view, favicon); });
$chromeTabViews.on('viewTitleUpdated', function (event, view, title, instance){ console.log('View title updated.', view, title); });
$chromeTabViews.on('viewStoppedLoading', function (event, view, instance){ console.log('View stopped loading.', view); });

Project Overview

Chrome Tabs

A tabbed interface (like Google Chrome). Designed for Electron, but also browser-compatible with a jQuery wrapper. This serves as a great example […]
Share This
Posted in: