2024-01-08 16:56:10 +00:00
# electron-tabs is discontinued
Thank you for your support and contributions all these years.
---
2016-10-31 15:10:14 +00:00
# electron-tabs
> Simple tabs for Electron applications
2022-05-25 15:38:16 +00:00
![Electron Tab Demo ](image.jpg )
2016-11-02 16:04:19 +00:00
2022-05-25 15:20:17 +00:00
## Features
2016-10-31 15:10:14 +00:00
2022-05-25 15:20:17 +00:00
* :electron: Compatible with Electron ≥ 17.
* :lock: Compliant with [Electron security recommendations ](https://www.electronjs.org/docs/latest/tutorial/security ) (works without `nodeIntegration: true` ).
* :toolbox: Written with TypeScript and Web Components.
* :hand: Supports drag and drop out of the box.
* :art: Easily customizable.
2016-11-01 15:28:30 +00:00
2022-05-25 15:20:17 +00:00
## Installation
2017-07-02 11:32:27 +00:00
2022-05-25 15:20:17 +00:00
```bash
npm install --save electron-tabs
2017-07-02 11:32:27 +00:00
```
2022-05-25 15:20:17 +00:00
## Getting started
2016-11-01 15:28:30 +00:00
2022-05-25 15:20:17 +00:00
Define the following `webPreferences` options in the main process:
2020-02-04 11:14:55 +00:00
```js
const mainWindow = new electron.BrowserWindow({
webPreferences: {
webviewTag: true
}
});
```
2022-05-25 15:20:17 +00:00
Then add the following markup where you want the tabs to display:
2016-10-31 15:10:14 +00:00
```html
2022-05-25 15:20:17 +00:00
< tab-group > < / tab-group >
2016-10-31 15:10:14 +00:00
2022-05-25 15:20:17 +00:00
< script src = "node_modules/electron-tabs/dist/electron-tabs.js" > < / script >
2016-11-01 15:28:30 +00:00
```
2016-10-31 15:10:14 +00:00
2022-05-25 15:20:17 +00:00
## Options
2016-10-31 15:10:14 +00:00
2022-05-25 15:20:17 +00:00
You can add options by setting `<tab-group>` element attributes:
2016-11-02 16:13:41 +00:00
```html
2022-05-25 15:20:17 +00:00
< tab-group new-tab-button = "true" sortable = "true" > < / tab-group >
2016-11-02 16:13:41 +00:00
```
2022-05-25 15:20:17 +00:00
The following attributes are supported:
2020-02-04 11:14:55 +00:00
2022-05-25 15:20:17 +00:00
* `close-button-text` (string): text of the tabs "Close" button.
* `new-tab-button` (boolean): set it to true to display the "New Tab" button.
* `new-tab-button-text` (string): text of the "New Tab" button.
* `sortable` (boolean): set it to true to make the tabs sortable by drag and drop.
* `visibility-threshold` (number): the minimum number of tabs necessary for the tab bar to be displayed. 0 (default) means that it will always remain visible.
2018-08-05 07:12:59 +00:00
2022-05-25 15:20:17 +00:00
## Methods
2016-11-01 15:28:30 +00:00
2022-05-25 15:20:17 +00:00
Use `TabGroup` methods and manipulate tabs in a script after calling `electron-tabs.js` .
2016-11-01 15:28:30 +00:00
2022-05-25 15:20:17 +00:00
```html
< tab-group new-tab-button = "true" > < / tab-group >
< script src = "path/to/electron-tabs.js" > < / script >
< script >
// Select tab-group
const tabGroup = document.querySelector("tab-group");
// Setup the default tab which is created when the "New Tab" button is clicked
tabGroup.setDefaultTab({
title: "New Page",
src: "path/to/new-page.html",
active: true
});
// Do stuff
const tab = tabGroup.addTab({
title: "electron-tabs on NPM",
src: "https://www.npmjs.com/package/electron-tabs"
});
const pos = tab.getPosition();
console.log("Tab position is " + pos);
< / script >
```
2016-11-01 15:28:30 +00:00
2022-05-25 15:20:17 +00:00
### TabGroup
2016-11-01 15:28:30 +00:00
#### `tabGroup.addTab(options)`
2022-05-25 15:20:17 +00:00
Add a new tab and returns the related `Tab` instance.
2016-11-01 15:28:30 +00:00
* `title` : tab title.
* `src` : URL to the page which will be loaded into the view. This is actually the same than `options.webview.src` .
2022-05-25 15:20:17 +00:00
* `badge` : optional text to put into a badge, badge will be hidden if false.
2016-11-01 15:28:30 +00:00
* `iconURL` : optional URL to the tab icon.
2017-02-15 19:47:18 +00:00
* `icon` : optional code for a tab icon. Can be used with symbol libraries (example with Font Awesome: `icon: 'fa fa-icon-name'` ). This attribute is ignored if an `iconURL` was given.
2016-11-01 15:28:30 +00:00
* `closable` (default: `true` ): if set to `true` the close button won't be displayed and the user won't be able to close the tab. See also `tab.close()` .
2016-11-02 15:37:05 +00:00
* `visible` (default: `true` ): set this to `false` if you don't want to display the tab once it is loaded. If set to `false` then you will need to call `tab.show()` to display the tab.
2016-11-02 15:37:23 +00:00
* `active` (default: `false` ): set this to `true` if you want to activate the tab once it is loaded. Otherwise you will need to call `tab.activate()` .
2016-11-01 15:28:30 +00:00
* `ready` : a callback function to call once the tab is ready. The `Tab` instance is passed as the only parameter.
2022-05-25 15:20:17 +00:00
* `webviewAttributes` : attributes to add to the webview tag. See [webview documentation ](http://electron.atom.io/docs/api/web-view-tag/#tag-attributes ).
2022-05-25 16:05:11 +00:00
#### `tabGroup.setDefaultTab(options)`
2022-05-25 15:20:17 +00:00
Define default options to use for creating the tab when the "New Tab" button is clicked or when calling `tabGroup.addTab()` with no parameter.
```javascript
tabGroup.setDefaultTab({
title: "New Page",
src: "path/to/new-page.html",
active: true
});
```
2016-11-01 15:28:30 +00:00
2017-11-19 15:31:26 +00:00
#### `tabGroup.getTab(id)`
2017-10-28 01:11:46 +00:00
Retrieve an instance of `Tab` from this `id` (return `null` if not found).
#### `tabGroup.getTabByPosition(position)`
2017-11-06 03:38:01 +00:00
Retrieve an instance of `Tab` from this `position` (return `null` if not found). A negative value is an offset from the right.
To get the tab in the leftmost position:
```javascript
tabGroup.getTabByPosition(1);
```
To get the tab in the rightmost position:
```javascript
tabGroup.getTabByPosition(-1);
```
#### `tabGroup.getTabByRelPosition(position)`
Retrieve an instance of `Tab` from this `position` relative to the active tab (return `null` if not found).
2022-05-25 15:20:17 +00:00
2017-11-06 03:38:01 +00:00
`tabGroup.getNextTab()` is an alias to `tabGroup.getTabByRelPosition(1)` .
2022-05-25 15:20:17 +00:00
2017-11-06 03:38:01 +00:00
`tabGroup.getPreviousTab()` is an alias to `tabGroup.getTabByRelPosition(-1)` .
2016-11-01 15:28:30 +00:00
#### `tabGroup.getActiveTab()`
2022-05-25 15:20:17 +00:00
Return the active tab (return `null` if none).
2016-11-01 15:28:30 +00:00
2017-09-14 15:23:49 +00:00
#### `tabGroup.getTabs()`
Return all registered tabs.
#### `tabGroup.eachTab(fn, thisArg)`
Loop through the list of tabs in `tabGroup` and execute the `fn` function for each tab. `fn` is called with the following parameters:
* `currentTab` : the current tab object.
* `index` : the index of the current tab being processed.
* `tabs` : the full array of tabs (similar to `tabGroup.getTabs()` ).
`thisArg` (optional) is the value to use as `this` when executing `fn` .
2016-11-01 15:28:30 +00:00
### Tab
Instances of `Tab` are returned by the `tabGroup.addTab()` method.
#### `tab.setTitle(title)`
Set tab title.
#### `tab.getTitle()`
Get current tab title.
2017-06-25 13:29:45 +00:00
#### `tab.setBadge(badge)`
Set tab badge.
#### `tab.getBadge()`
Get current tab badge.
2017-02-15 19:47:18 +00:00
#### `tab.setIcon (iconURL, icon)`
2016-11-01 15:28:30 +00:00
2017-02-15 19:47:18 +00:00
Set tab icon (a iconURL or an icon must be given).
2016-11-01 15:28:30 +00:00
#### `tab.getIcon()`
2017-02-15 19:47:18 +00:00
Get current tab icon URL / icon.
2016-11-01 15:28:30 +00:00
2017-10-27 00:03:37 +00:00
#### `tab.setPosition(newPosition)`
2022-05-25 15:20:17 +00:00
Move tab to the specified position. See [`tabGroup.getTabByPosition` ](#tabgroupgettabbypositionposition ) for information about positions.
2017-10-27 01:55:12 +00:00
#### `tab.getPosition(fromRight)`
2017-10-27 02:13:19 +00:00
Get the tab position. If `fromRight` is true the index returned is negative and is the offset from the right.
2017-10-27 00:03:37 +00:00
2016-11-01 15:28:30 +00:00
#### `tab.activate()`
Activate this tab. The class "active" is added to the active tab.
#### `tab.show(flag)`
Toggle the "visible" class on the tab. `tab.hide()` is an alias to `tab.show(false)` .
2020-03-12 20:56:23 +00:00
#### `tab.hasClass(classname)`
2022-05-25 15:20:17 +00:00
Return `true` if the tab element has the specified classname. Useful for checking if a tab is "active" or "visible".
2020-03-12 20:56:23 +00:00
2016-11-01 15:28:30 +00:00
#### `tab.close(force)`
Close the tab (and activate another tab if relevant). When `force` is set to `true` the tab will be closed even if it is not `closable` .
2022-05-25 15:20:17 +00:00
## Events
2016-11-01 15:28:30 +00:00
2022-05-25 15:20:17 +00:00
The following events are emitted:
2016-11-01 15:28:30 +00:00
* `tabGroup.on("tab-added", (tab, tabGroup) => { ... });`
* `tabGroup.on("tab-removed", (tab, tabGroup) => { ... });`
* `tabGroup.on("tab-active", (tab, tabGroup) => { ... });`
2017-02-16 15:13:07 +00:00
* `tab.on("webview-ready", (tab) => { ... });`
2020-02-28 09:33:20 +00:00
* `tab.on("webview-dom-ready", (tab) => { ... });`
2016-11-01 15:28:30 +00:00
* `tab.on("title-changed", (title, tab) => { ... });`
2022-03-23 19:26:24 +00:00
* `tab.on("badge-changed", (badge, tab) => { ... });`
2017-02-15 19:47:18 +00:00
* `tab.on("icon-changed", (icon, tab) => { ... });`
2016-11-01 15:28:30 +00:00
* `tab.on("active", (tab) => { ... });`
2019-09-24 06:09:53 +00:00
* `tab.on("inactive", (tab) => { ... });`
2016-11-01 15:28:30 +00:00
* `tab.on("visible", (tab) => { ... });`
* `tab.on("hidden", (tab) => { ... });`
* `tab.on("close", (tab) => { ... });`
2020-03-10 21:38:20 +00:00
* `tab.on("closing", (tab, abort) => { ... });` (Use `abort()` function to cancel closing)
2016-11-01 15:28:30 +00:00
2022-03-23 19:26:24 +00:00
You can also use `tab.once` to automatically remove the listener when invoked:
* `tab.once("webview-ready", (tab) => { ... });`
* `tab.once("webview-dom-ready", (tab) => { ... });`
2022-05-25 15:20:17 +00:00
## Access Electron webview element
2016-11-02 17:19:56 +00:00
2022-05-25 15:20:17 +00:00
You can access the webview element and use its methods with through the `Tab.webview` attribute. See [webview documentation ](https://electronjs.org/docs/api/webview-tag#methods ).
2016-11-02 17:19:56 +00:00
2022-05-25 15:20:17 +00:00
```javascript
let webview = tab.webview;
webview.loadURL("file://path/to/new/page.html");
2016-11-02 17:19:56 +00:00
```
2022-05-25 15:20:17 +00:00
## Custom styles
To customize tab-group styles, set new values to [electron-tabs CSS variables ](https://github.com/brrd/electron-tabs/blob/master/src/style.css ) in your application stylesheet.
Since `TabGroup` is a Web Component you won't be able to change its styles directly from your app stylesheet. If you need more control over it then you can add a `<style>` tag inside the `<tab-group >` element:
```html
< tab-group new-tab-button = "true" sortable = "true" >
< style >
/* Write your own CSS rules here... */
< / style >
< / tab-group >
2016-11-02 17:19:56 +00:00
```
2022-05-25 15:20:17 +00:00
This method is particularly useful when you need to define custom badges or tab styles:
2016-11-02 17:19:56 +00:00
```html
2022-05-25 15:20:17 +00:00
< tab-group new-tab-button = "true" sortable = "true" >
< style >
/* Add custom styles */
.my-badge {
background-color: orange;
}
.my-custom-tab {
color: red;
font-weight: bold;
}
< / style >
< / tab-group >
< script src = "path/to/electron-tabs.js" > < / script >
< script >
const tabGroup = document.querySelector("tab-group");
tabGroup.addTab({
title: "Tab with custom badge",
src: "page.html",
badge: {
text: "5",
classname: "my-badge"
}
});
tabGroup.addTab({
title: "Tab with custom style",
src: "page.html",
ready: function(tab) {
tab.element.classList.add("my-custom-tab");
}
});
< / script >
2016-11-02 17:19:56 +00:00
```
2022-05-25 15:20:17 +00:00
## Development
2016-11-02 17:19:56 +00:00
2022-05-25 15:20:17 +00:00
`electron-tabs` uses TypeScript and Parcel under the hood.
### Requirements
Git and Node 12+.
### Build
```bash
# Clone this repo
git clone git@github.com:brrd/electron-tabs.git
cd electron-tabs
# Install dependencies
npm install
# Build
npm run build
# ...or watch
npm run watch
```
### Demo
```bash
npm run demo
2016-11-02 17:19:56 +00:00
```
2016-10-31 15:10:14 +00:00
## License
2022-05-25 15:20:17 +00:00
The MIT License (MIT) - Copyright (c) 2022 Thomas Brouard