Tab

The Tab class represents a single tab within Flow Browser. It encapsulates an Electron WebContentsView, manages state (URL, title, loading status, audio), handles layout, and coordinates lifecycle events like sleep/wake.

Overview

Each Tab instance:

Manages a WebContentsView and WebContents for rendering web pages
Tracks state: URL, title, loading, audio, favicon, visibility
Supports different layouts (normal, glance, split)
Handles lifecycle: creation, sleep/wake, and destruction
Emits events for focus changes, updates, and destruction

Creating a Tab

Tabs are created through the TabsController:

import { tabsController } from '@/controllers/tabs-controller';

// Create a new tab
const tab = await tabsController.createTab(
  windowId,
  'profile-id',
  'space-id',
  undefined,
  { url: 'https://example.com' }
);

TabCreationDetails

Required details passed to the Tab constructor:

tabsController

TabsController

required

The TabsController instance managing this tab

profileId

string

required

ID of the user profile associated with this tab

spaceId

string

required

ID of the space this tab belongs to

session

Session

required

Electron Session object for this tab’s web content

loadedProfile

LoadedProfile

required

The loaded profile instance

TabCreationOptions

Optional configuration for tab creation:

window

BrowserWindow

required

The window to attach the tab to

uniqueId

string

Custom unique ID (auto-generated if not provided)

webContentsViewOptions

WebContentsViewConstructorOptions

Electron WebContentsView customization options

url

string

Initial URL to load

asleep

boolean

Whether to create the tab in sleep mode (no WebContents, saves memory)

position

number

Tab position in the tab strip

title

string

Restored title (for sleeping tabs)

faviconURL

string

Restored favicon URL

navHistory

NavigationEntry[]

Navigation history to restore

navHistoryIndex

number

Active index in navigation history

Properties

Identity & Organization

number

Unique tab ID (stable across sleep/wake cycles)

uniqueId

string

Persistent unique identifier

profileId

string

Associated profile ID (readonly)

spaceId

string

Associated space ID (can be changed with setSpace())

groupId

string | null

ID of the tab group this tab belongs to (if any)

State Properties

visible

boolean

Whether the tab’s view is currently visible

isDestroyed

boolean

Whether the tab has been destroyed

asleep

boolean

Whether the tab is in sleep mode (no WebContents to save memory)

fullScreen

boolean

Whether the tab is in fullscreen mode

isPictureInPicture

boolean

Whether the tab has an active picture-in-picture window

position

number

Tab position in the tab strip

lastActiveAt

number

Timestamp when tab was last active

Content Properties

title

string

Current page title (default: “New Tab”)

url

string

Current page URL

isLoading

boolean

Whether the page is currently loading

faviconURL

string | null

URL of the current favicon

audible

boolean

Whether the tab is playing audio

muted

boolean

Whether the tab’s audio is muted

navHistory

NavigationEntry[]

Navigation history entries

navHistoryIndex

number

Current index in navigation history

View Objects

view

PatchedWebContentsView | null

The Electron WebContentsView instance (null when tab is asleep)

webContents

WebContents | null

The Electron WebContents instance (null when tab is asleep)

Methods

loadURL

(url: string, replace?: boolean) => void

Loads a URL in the tabParameters:

url: URL to load
replace: If true, replaces current history entry instead of creating new one

tab.loadURL('https://example.com');
tab.loadURL('https://example.com', true); // Replace history

loadErrorPage

(errorCode: number, url: string) => void

Loads a custom error page for the given error code and URL

tab.loadErrorPage(-105, 'https://invalid-url.com');

Window & Space Management

setWindow

(window: BrowserWindow, index?: number) => void

Attaches the tab’s view to a window or moves it to a different windowParameters:

window: Target window
index: View layer index (default: ViewLayer.TAB)

tab.setWindow(newWindow);

getWindow

() => BrowserWindow

Returns the current window for the tab

setSpace

(spaceId: string) => void

Changes the space assignment for the tab

tab.setSpace('work-space');

Visibility

show

() => void

Makes the tab’s view visible

hide

() => void

Hides the tab’s view

State Updates

updateTabState

() => boolean

Reads current state from webContents and emits ‘updated’ event if anything changedReturns true if state changed, false otherwise.

const changed = tab.updateTabState();

scheduleUpdateTabState

() => void

Schedules an updateTabState() call via queueMicrotask. Multiple calls are coalesced.

updateStateProperty

<T>(property: TabStateProperty, newValue: T) => boolean

Updates a single state property with change detection and emits ‘updated’ event

View Lifecycle

initializeView

() => void

Creates the WebContentsView, sets up listeners, and registers with extensions. Called on wake from sleep.

teardownView

() => void

Destroys the WebContentsView and frees resources. Called when putting tab to sleep.

Restores navigation history on the current webContents

applyUrlBackground

() => void

Applies the correct background color based on the current URL (transparent for internal protocols)

Destruction

destroy

() => void

Destroys the tab and cleans up resources. Emits ‘destroyed’ event.

tab.destroy();

Events

The Tab class extends TypedEventEmitter and emits:

focused

[]

Emitted when the tab’s webContents gains focus

tab.on('focused', () => {
  console.log('Tab focused');
});

updated

[TabPublicProperty[]]

Emitted when tab state changes (title, URL, loading status, favicon, visibility, etc.)

tab.on('updated', (changedProperties) => {
  console.log('Changed properties:', changedProperties);
});

destroyed

[]

Emitted when the tab is destroyed

tab.on('destroyed', () => {
  console.log('Tab destroyed');
});

space-changed

[]

Emitted when the tab’s space assignment changes

window-changed

[oldWindowId: number]

Emitted when the tab moves to a different window

fullscreen-changed

[boolean]

Emitted when fullscreen state changes

new-tab-requested

[url: string, disposition: string, options?: WebContentsViewConstructorOptions, details?: HandlerDetails]

Emitted when the page requests opening a new tab (e.g., target=“_blank” links)

Sleep Mode

Tabs can be put to sleep to save memory (~20-50MB per sleeping tab):

const managers = tabsController.getTabManagers(tab.id);
managers?.lifecycle.putToSleep();

When asleep:

tab.view and tab.webContents are null
Visual state (title, URL, favicon) is preserved
Navigation history is stored

Wake from sleep:

managers?.lifecycle.wakeFromSleep();

The tab automatically recreates the WebContentsView and restores navigation history.

Example: Managing Tab State

import { tabsController } from '@/controllers/tabs-controller';

// Create tab
const tab = await tabsController.createTab();

// Listen for updates
tab.on('updated', (properties) => {
  if (properties.includes('title')) {
    console.log('Title changed:', tab.title);
  }
  if (properties.includes('url')) {
    console.log('URL changed:', tab.url);
  }
});

// Load URL
tab.loadURL('https://example.com');

// Check loading state
if (tab.isLoading) {
  console.log('Page is loading...');
}

// Mute audio
if (tab.audible && tab.webContents) {
  tab.webContents.setAudioMuted(true);
}

Browser

Learn about browser controllers

Window

Learn about BrowserWindow

Core APIs

Controllers

Extensions

IPC

Overview

Creating a Tab

TabCreationDetails

TabCreationOptions

Properties

Identity & Organization

State Properties

Content Properties

View Objects

Methods

Navigation

Window & Space Management

Visibility

State Updates

View Lifecycle

Destruction

Events

Sleep Mode

Example: Managing Tab State

Browser

Window

Build docs developers (and LLMs) love

Core APIs

Controllers

Extensions

IPC

​Overview

​Creating a Tab

​TabCreationDetails

​TabCreationOptions

​Properties

​Identity & Organization

​State Properties

​Content Properties

​View Objects

​Methods

​Navigation

​Window & Space Management

​Visibility

​State Updates

​View Lifecycle

​Destruction

​Events

​Sleep Mode

​Example: Managing Tab State

​Related

Browser

Window

Build docs developers (and LLMs) love

Overview

Creating a Tab

TabCreationDetails

TabCreationOptions

Properties

Identity & Organization

State Properties

Content Properties

View Objects

Methods

Navigation

Window & Space Management

Visibility

State Updates

View Lifecycle

Destruction

Events

Sleep Mode

Example: Managing Tab State

Related