Extension API

All the APIs documented are available through the browser namespace.

Tip

For compatibility reasons, Webfuse provides chrome as an alias to the browser namespace. You can use both interchangeably.

.webfuseSession Scope Webfuse Exclusive

The webfuseSession namespace contains methods specific to Webfuse sessions. This is the primary API for interacting with Webfuse functionality from within an extension. The webfuseSession namespace acts as a proxy to the Session API and exposes the following methods for convenience, for example:

• browser.webfuseSession.log()
• browser.webfuseSession.getParticipants()
• browser.webfuseSession.getSessionInfo()
• browser.webfuseSession.end()
• …

.runtime Scope

The runtime namespace targets the browser in general.

runtime.sendMessage()

Sends a message to the following components of the extension: Popup, Background, Newtab page.

browser.runtime.sendMessage(message: unknown): void

Parameters

message

• The message to send.

Note

If you want to send a message to the content script of a specific tab you can use browser.tabs.sendMessage().

runtime.onMessage.addListener()

browser.runtime.onMessage.addListener(callback: (message: unknown) => void): void

Listens for messages from the extension.

Parameters

callback

• The callback function to handle the message.

Example

browser.runtime.onMessage.addListener((message, sender) => {});

.tabs Scope

The tabs namespace contains methods for managing tabs, overriding standard Chrome APIs to work with Webfuse sessions.

tabs.sendMessage()

browser.tabs.sendMessage(tabId: number, message: unknown, options: {
    frameId?: number;
}): Promise<unknown | null>

Sends a message from any component to the content script of that specific tab.

Parameters

tabId

• The tabId to send the message to. Can be queried via getTabs() method. Passing null will send the message to all tabs.

message

• The message to send. Must be a JSON-serializable object.

options

• Additional options for message delivery:
• frameId Send the message to a specific frame within the tab.

Returns

Returns a promise that resolves with the response from the content script’s message handler.

Frame Targeting

By default, messages are sent to the main frame of the tab. Use the frameId option to target specific frames:

// Send to main frame (default)
browser.tabs.sendMessage(tabId, { greeting: "Hello main frame" });

// Send to specific frame
browser.tabs.sendMessage(tabId, { greeting: "Hello frame" }, { frameId: 123 });

Note

Frame targeting depends on the all_frames setting in your manifest.json content scripts configuration.

Tip

For more information about extension messaging please refer to the Extension Messaging page.

webNavigation.getAllFrames()

browser.webNavigation.getAllFrames(details: {
    tabId: number;
}): Promise<Frame[]>

Retrieves information about all frames in a tab.

Parameters

details

• Query details:
• tabId The ID of the tab to query.

Returns

Returns a Promise that resolves with an array of Frame objects.

.browserAction Scope

The browserAction namespace contains methods for managing the extension popup. For security reasons browserAction methods are available in all extension components except the content script.

browserAction.openPopup()

Open the extension popup.

browser.browserAction.openPopup(): void

browserAction.closePopup()

Close the extension popup.

browser.browserAction.closePopup(): void

browserAction.resizePopup()

Resize the extension popup. If no parameters are provided, the popup will be resized to its default size.

browser.browserAction.resizePopup(width: number, height: number): void

Parameters

width

• The width of the popup.

height

• The height of the popup.

browserAction.setPopupStyles()

Set the styles of the extension popup. Default styles are background: white, minWidth: 300px, minHeight: 200px and can be overridden.

browser.browserAction.setPopupStyles(styles: Record<string, string | number>): void

Parameters

styles

• An object containing CSS properties and values to set. Allowed properties:
  • Background & Direction: backgroundColor, direction
  • Spacing: padding, paddingTop, paddingRight, paddingBottom, paddingLeft, margin, marginTop, marginRight, marginBottom, marginLeft
  • Borders: border, borderWidth, borderColor, borderStyle, borderRadius, borderTop, borderTopWidth, borderTopColor, borderTopStyle, borderRight, borderRightWidth, borderRightColor, borderRightStyle, borderBottom, borderBottomWidth, borderBottomColor, borderBottomStyle, borderLeft, borderLeftWidth, borderLeftColor, borderLeftStyle, borderTopLeftRadius, borderTopRightRadius, borderBottomRightRadius, borderBottomLeftRadius
  • Visual Effects: boxShadow, overflow, overflowX, overflowY, resize

Other properties will be ignored.

Note

For positioning the popup, use browserAction.setPopupPosition() instead. For sizing, use browserAction.resizePopup().

Examples

// Set background and direction
browser.browserAction.setPopupStyles({
    backgroundColor: 'transparent',
    direction: 'rtl'
});

// Add padding and borders
browser.browserAction.setPopupStyles({
    padding: '20px',
    border: '2px solid #3b82f6',
    borderRadius: '12px'
});

// Add shadow and overflow
browser.browserAction.setPopupStyles({
    boxShadow: '0 10px 25px rgba(0, 0, 0, 0.3)',
    overflow: 'auto'
});

browserAction.setPopupPosition()

Set the position of the extension popup on the screen. The popup will be positioned with position: fixed.

browser.browserAction.setPopupPosition(position: {
  top?: string;
  bottom?: string;
  left?: string;
  right?: string;
}): void

Parameters

position

• An object containing CSS positioning properties. Allowed properties: top, right, bottom, left. Values should be strings with CSS units (e.g., '20px', '10%', 'calc(100vh - 50px)', etc.).

Other properties will be ignored.

Examples

// Position at top-right corner
browser.browserAction.setPopupPosition({ top: '20px', right: '50px' });

// Position at bottom-left corner
browser.browserAction.setPopupPosition({ bottom: '40px', left: '60px' });

// Position at top-left corner
browser.browserAction.setPopupPosition({ top: '10px', left: '10px' });

browserAction.getPopupPosition()

Get the current position of the extension popup.

browser.browserAction.getPopupPosition(): Promise<{
  top?: string;
  bottom?: string;
  left?: string;
  right?: string;
}>

Returns

Returns a promise that resolves with an object containing the current popup position properties (top, bottom, left, right). Returns an empty object {} if no position has been set via setPopupPosition() or if the popup has not been opened yet.

Tip

See the Draggable Popup Extension example for a complete implementation.

browserAction.disablePopup()

Disable the extension popup. When the extension icon and popup are not rendered and all other browserAction methods related to the popup will not be available.

browser.browserAction.disablePopup(tabId?: number): void

Parameters

tabId

• The tabId to disable the popup for. If not provided, the popup will be disabled for all tabs.

Example

browser.browserAction.disablePopup();
browser.browserAction.disablePopup(1000);

browserAction.enablePopup()

Enable the extension popup.

browser.browserAction.enablePopup(tabId?: number): void

Parameters

tabId

• The tabId to enable the popup for. If not provided, the popup will be enabled for all tabs.

Example

browser.browserAction.enablePopup();
browser.browserAction.enablePopup(1000);

browserAction.setPopupBadgeText()

Set the badge text of the extension popup.

browser.browserAction.setPopupBadgeText(text: string, tabId?: number): void

Parameters

text

• The text to set as the badge text. Any number of characters can be passed, but only about two can fit into the space. If a falsy value is passed, the badge text is cleared.

tabId

• The tabId to set the badge text for. If not provided, the badge text will be set for all tabs.

Example

browser.browserAction.setPopupBadgeText('1');
browser.browserAction.setPopupBadgeText('1', 1000);

browserAction.getPopupBadgeText()

Get the current badge text of the extension popup.

browser.browserAction.getPopupBadgeText(tabId?: number): Promise<{ text: string }>

Parameters

tabId

• The tabId to get the badge text for. If not provided, the badge text will be retrieved for an active tab.

Returns

Returns a promise that resolves with an object containing the current badge text.

Example

// Get badge text for active tab
const text = await browser.browserAction.getPopupBadgeText();
// Get badge text for specific tab
const text = await browser.browserAction.getPopupBadgeText(1000);

browserAction.setPopupBadgeBackgroundColor()

Set the background color of the extension popup badge.

browser.browserAction.setPopupBadgeBackgroundColor(color: string, tabId?: number): void

Parameters

color

• The background color to set as the badge color. Any valid CSS color value can be passed. If a falsy value is passed, the badge color is cleared and the default color is used.

tabId

• The tabId to set the badge color for. If not provided, the badge color will be set for all tabs.

Example

browser.browserAction.setPopupBadgeBackgroundColor('#3b82f6');
browser.browserAction.setPopupBadgeBackgroundColor('red');
browser.browserAction.setPopupBadgeBackgroundColor('rgba(255, 0, 0, 0.5)');
browser.browserAction.setPopupBadgeBackgroundColor('#3b82f6', 1000);

browserAction.getPopupBadgeBackgroundColor()

Get the current background color of the extension popup badge.

browser.browserAction.getPopupBadgeBackgroundColor(tabId?: number): Promise<{ color: string }>

Parameters

tabId

• The tabId to get the badge color for. If not provided, the badge color will be retrieved for an active tab.

Returns

Returns a promise that resolves with an object containing the current custom background color of the extension popup badge. If no custom color is set an empty string is returned.

Example

// Get badge color for active tab
const color = await browser.browserAction.getPopupBadgeBackgroundColor();
// Get badge color for specific tab
const color = await browser.browserAction.getPopupBadgeBackgroundColor(1000);

browserAction.setPopupTitle()

Set the title of the extension popup.

browser.browserAction.setPopupTitle(title: string, tabId?: number): void

Parameters

title

• The title to set as the popup title. Any number of characters can be passed. If a falsy value is passed, the popup title is cleared.

tabId

• The tabId to set the popup title for. If not provided, the popup title will be set for all tabs.

Example

browser.browserAction.setPopupTitle('My Extension');
browser.browserAction.setPopupTitle('My Extension', 1000);

browserAction.getPopupTitle()

Get the current title of the extension popup.

browser.browserAction.getPopupTitle(tabId?: number): Promise<{ title: string }>

Parameters

tabId - The tabId to get the popup title for. If not provided, the popup title will be retrieved for an active tab.

Returns

Returns a promise that resolves with an object containing the current title of the extension popup.

Example

// Get popup title for active tab
const title = await browser.browserAction.getPopupTitle();
// Get popup title for specific tab
const title = await browser.browserAction.getPopupTitle(1000);

browserAction.setPopupIcon()

Set the icon of the extension in the top bar.

browser.browserAction.setPopupIcon(icon: string, tabId?: number): void

Parameters

icon

• The icon to set as the extension’s icon. It can be a file path relative to the root folder of the extension directory or a data URL. If a falsy value is passed, the icon is cleared, and the default icon is used.

tabId

• The tabId to set the icon for. If not provided, the icon will be set for all tabs.

Example

browser.browserAction.setPopupIcon('icons/icon.png');
browser.browserAction.setPopupIcon('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==');
browser.browserAction.setPopupIcon('icons/icon.png', 1000);

browserAction.setPopup()

Set the popup of the extension.

browser.browserAction.setPopup(popup: string, tabId?: number): void

Parameters

popup - Path to the template file to set as the extension popup. It must be an extension directory file path relative to the root folder. If a falsy value is passed, the popup is cleared and the default popup is used.

tabId

• The tabId to set the popup for. If not provided, the popup will be set for all tabs.

Example

browser.browserAction.setPopup('popup.html');
browser.browserAction.setPopup('popup.html', 1000);

browserAction.getPopup()

Get the current popup of the extension.

browser.browserAction.getPopup(tabId?: number): Promise<{ popup: string }>

Parameters

tabId - The tabId to get the popup for. If not provided, the popup will be retrieved for an active tab.

Returns

Returns a promise that resolves with an object containing the url of the current popup of the extension.

Example

// Get popup for active tab
const popup = await browser.browserAction.getPopup();
// Get popup for specific tab
const popup = await browser.browserAction.getPopup(1000);

Events

browserAction.onClicked

Triggers when the extension icon in the top bar is clicked. If the extension has a default popup or the popup is disabled, the event will not be triggered.

browser.browserAction.onClicked.addListener

Adds a listener for the extension icon click event.

browser.browserAction.onClicked.addListener(callback: (tab: Tab) => void): string

Parameters

callback

• The callback function to handle the event. Tab object represents the tab on which the extension icon was clicked.

Returns

Returns a handler key that can be used to remove the listener.

Example

const handlerKey = browser.browserAction.onClicked.addListener((tab) => {
    console.log('Extension icon clicked on tab:', tab);
});

browser.browserAction.onClicked.removeListener

Removes a listener for the extension icon click event.

browser.browserAction.onClicked.removeListener(handlerKey: string): boolean

Parameters

handlerKey

• The handler key to remove.

Returns

Returns a boolean indicating if the listener was removed successfully.

Example

browser.browserAction.onClicked.removeListener(handlerKey);

browser.browserAction.onClicked.hasListener

Checks if a listener for the extension icon click event is registered.

browser.browserAction.onClicked.hasListener(handlerKey: string): boolean

Parameters

handlerKey

• The handler key to check.

Returns

Returns a boolean indicating if the listener is registered.

Example

const hasListener = browser.browserAction.onClicked.hasListener(handlerKey);
console.log(hasListener);

Tip

The listener will be created in the extension component where it is defined, meaning that if you create the listener in the Start Page component and the page is closed, the listener will be removed. Taking this into account, if you want to create a listener that will persists during the session, the best place to do so is in the background.service_worker script.

.sidePanel Scope

The sidePanel namespace contains methods for managing the extension side panel. For security reasons, the sidePanel namespace is available for all extension components except content script.

sidePanel.open()

Open the extension side panel.

browser.sidePanel.open({ tabId?: number }): void

Parameters

tabId

• The tabId to open the side panel for. If not provided, the side panel will be opened for all tabs.

sidePanel.close()

Close the extension side panel.

browser.sidePanel.close({ tabId?: number }): void

Parameters

tabId

• The tabId to close the side panel for. If not provided, the side panel will be closed for all tabs.

sidePanel.setOptions()

Set the options of the extension side panel.

browser.sidePanel.setOptions({ path?: string, enabled?: boolean, tabId?: number }): void

Parameters

path

• The path to the side panel template file relative to the root folder of the extension directory.

enabled

• Whether the side panel is enabled.

tabId

• The tabId to set the side panel options for. If not provided, the side panel options will be set for all tabs.

Example

browser.sidePanel.setOptions({ path: '/side_panel.html' });
browser.sidePanel.setOptions({ path: '/side_panel.html', tabId: 1000 });
browser.sidePanel.setOptions({ enabled: false, path: '/side_panel.html', tabId: 1000 });

sidePanel.getOptions()

Get the options of the extension side panel.

browser.sidePanel.getOptions({ tabId?: number }): Promise<{ path?: string, enabled?: boolean, tabId?: number }>

Parameters

tabId

• The tabId to get the side panel options for. If not provided, the side panel options will be retrieved for an active tab.

Returns

Returns a promise that resolves with an object containing the current options of the extension side panel.

Example

const options = await browser.sidePanel.getOptions({ tabId: 1000 });
console.log(options);

sidePanel.setLayout()

Set the layout of the extension side panel.

browser.sidePanel.setLayout({ side: 'left' | 'right', tabId?: number }): void

Parameters

side

• The side of the extension side panel to set the layout for. It must be either left or right.

tabId

• The tabId to set the side panel layout for. If not provided, the side panel layout will be set for all tabs.

Example

browser.sidePanel.setLayout({ side: 'left' });
browser.sidePanel.setLayout({ side: 'left', tabId: 1000 });
browser.sidePanel.setLayout({ side: 'right', tabId: 1000 });

sidePanel.getLayout()

Get the layout of the extension side panel.

browser.sidePanel.getLayout({ tabId?: number }): Promise<{ side: 'left' | 'right', tabId?: number }>

Parameters

tabId

• The tabId to get the side panel layout for. If not provided, the side panel layout will be retrieved for an active tab.

Returns

Returns a promise that resolves with an object containing the current layout of the extension side panel and the tabId it is set for.

Example

const layout = await browser.sidePanel.getLayout({ tabId: 1000 });
console.log(layout);

sidePanel.setPanelBehavior()

Set the behavior of the extension side panel.

browser.sidePanel.setPanelBehavior({ openPanelOnActionClick?: boolean }): void

Parameters

openPanelOnActionClick

• Whether the side panel should be opened on action click. Default value is false.

Example

browser.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });

sidePanel.getPanelBehavior()

Get the behavior of the extension side panel.

browser.sidePanel.getPanelBehavior(): Promise<{ openPanelOnActionClick?: boolean }>

Returns

Returns a promise that resolves with an object containing the current behavior of the extension side panel.

Example

const behavior = await browser.sidePanel.getPanelBehavior();
console.log(behavior);