browserAction API

Use the action API to add a button to Thunderbird’s unified toolbar. In addition to its icon, an action button can also have a tooltip, a badge, and a popup.

Manifest file properties

browser_action

[browser_action]

(object, optional)

– [Added in TB 64]

allowed_spaces

[allowed_spaces]

(array of string, optional)

– [Added in TB 115]

Defines for which spaces the browserAction button will be added to Thunderbird’s unified toolbar. Defaults to only allowing the browserAction in the mail space. The default space is for tabs that don’t belong to any space. If this is an empty array, the browserAction button is shown in all spaces.

Supported values:

addressbook

calendar

chat

default

mail

settings

tasks

browser_style

[browser_style]

(boolean, optional)

– [Added in TB 64]

Enable browser styles. See the MDN documentation on browser styles for more information.

default_area

[default_area]

(string, optional)

– [Added in TB 64]

Defines the location the browserAction button will appear. Deprecated and ignored. Replaced by allowed_spaces

Supported values:

maintoolbar

maintoolbar

– [Added in TB 92]

tabstoolbar

tabstoolbar

– [Added in TB 92]

default_icon

[default_icon]

(IconPath, optional)

– [Added in TB 64]

The paths to one or more icons for the browserAction button.

default_label

[default_label]

(string, optional)

– [Added in TB 85]

The label of the browserAction button, defaults to its title. Can be set to an empty string to not display any label. If the containing toolbar is configured to display text only, the title will be used as fallback.

default_popup

[default_popup]

(string, optional)

– [Added in TB 64]

The html document to be opened as a popup when the user clicks on the browserAction button. Ignored for action buttons with type menu.

default_title

[default_title]

(string, optional)

– [Added in TB 64]

The title of the browserAction button. This shows up in the tooltip and the label. Defaults to the add-on name.

default_windows

[default_windows]

(array of string, optional)

– [Added in TB 115]

Defines the windows, the browserAction button should appear in. Defaults to showing it only in the normal Thunderbird window, but can also be shown in the messageDisplay window.

Supported values:

messageDisplay

normal

theme_icons

[theme_icons]

(array of ThemeIcons, optional)

– [Added in TB 64]

Specifies dark and light icons to be used with themes. The light icon is used on dark backgrounds and vice versa. The default theme uses the default_icon for light backgrounds (if specified).

type

[type]

(string, optional)

– [Added in TB 90]

Specifies the type of the button. Default type is button.

Supported values:

button

button

menu

menu

Permissions

Note

A manifest entry named browser_action is required to use messenger.browserAction.*.

Functions

disable([tabId])

– [Added in TB 64]

Disables the action button for a specific tab (if a tabId is provided), or for all tabs which do not have a custom enable state. Once the enable state of a tab has been updated individually, all further changes to its state have to be done individually as well.

Parameters

tabId

[tabId]

(integer, optional)

The id of the tab for which you want to modify the action button.

enable([tabId])

– [Added in TB 64]

Enables the action button for a specific tab (if a tabId is provided), or for all tabs which do not have a custom enable state. Once the enable state of a tab has been updated individually, all further changes to its state have to be done individually as well. By default, an action button is enabled.

Parameters

tabId

[tabId]

(integer, optional)

The id of the tab for which you want to modify the action button.

getBadgeBackgroundColor(details)

– [Added in TB 64]

Gets the badge background color of the action button.

Parameters

details

details

(object)

tabId

[tabId]

(integer, optional)

– [Added in TB 108]

Specifies for which tab the badge background color should be retrieved. If no tab is specified, the global value is retrieved.

windowId

[windowId]

(integer, optional) Unsupported.

– [Added in TB 108]

Will throw an error if used.

Return type (Promise)

_returns

getBadgeText(details)

– [Added in TB 64]

Gets the badge text of the action button.

Parameters

details

details

(object)

tabId

[tabId]

(integer, optional)

– [Added in TB 108]

Specifies for which tab the badge text should be retrieved. If no tab is specified, the global value is retrieved.

windowId

[windowId]

(integer, optional) Unsupported.

– [Added in TB 108]

Will throw an error if used.

Return type (Promise)

_returns

string

getBadgeTextColor(details)

– [Added in TB 128]

Gets the text color of the badge.

Parameters

details

details

(object)

tabId

[tabId]

(integer, optional)

Specifies for which tab the badge text color should be retrieved. If no tab is specified, the global value is retrieved.

windowId

[windowId]

(integer, optional) Unsupported.

Will throw an error if used.

Return type (Promise)

_returns

getLabel(details)

– [Added in TB 85]

Gets the label of the action button. Returns null, if no label has been set and the title is used.

Parameters

details

details

(object)

tabId

[tabId]

(integer, optional)

– [Added in TB 108]

Specifies for which tab the label should be retrieved. If no tab is specified, the global value is retrieved.

windowId

[windowId]

(integer, optional) Unsupported.

– [Added in TB 108]

Will throw an error if used.

Return type (Promise)

_returns

string or null

getPopup(details)

– [Added in TB 64]

Gets the html document set as the popup for this action button.

Parameters

details

details

(object)

tabId

[tabId]

(integer, optional)

– [Added in TB 108]

Specifies for which tab the popup document should be retrieved. If no tab is specified, the global value is retrieved.

windowId

[windowId]

(integer, optional) Unsupported.

– [Added in TB 108]

Will throw an error if used.

Return type (Promise)

_returns

string

getTitle(details)

– [Added in TB 64]

Gets the title of the action button.

Parameters

details

details

(object)

tabId

[tabId]

(integer, optional)

– [Added in TB 108]

Specifies for which tab the title should be retrieved. If no tab is specified, the global value is retrieved.

windowId

[windowId]

(integer, optional) Unsupported.

– [Added in TB 108]

Will throw an error if used.

Return type (Promise)

_returns

string

isEnabled(details)

– [Added in TB 64]

Checks whether the action button is enabled.

Parameters

details

details

(object)

tabId

[tabId]

(integer, optional)

– [Added in TB 108]

Specifies for which tab the state should be retrieved. If no tab is specified, the global value is retrieved.

windowId

[windowId]

(integer, optional) Unsupported.

– [Added in TB 108]

Will throw an error if used.

Return type (Promise)

_returns

boolean

– [Added in TB 89]

openPopup([options])

– [Added in TB 64]

Opens the action’s popup window in the specified window. Defaults to the current window. Returns false if the popup could not be opened because the action has no popup, is of type menu, is disabled or has been removed from the toolbar.

Parameters

options

[options]

(object, optional)

– [Added in TB 113]

An object with information about the popup to open.

windowId

[windowId]

(integer, optional)

– [Added in TB 113]

Defaults to the current window.

Return type (Promise)

_returns

boolean

– [Added in TB 113]

setBadgeBackgroundColor(details)

– [Added in TB 64]

Sets the background color for the badge.

Parameters

details

details

(object)

color

color

(string or ColorArray or null)

The color to use as background in the badge. Cleared by setting it to null.

tabId

[tabId]

(integer, optional)

Sets the background color for the badge only for the given tab.

windowId

[windowId]

(integer, optional) Unsupported.

Will throw an error if used.

setBadgeText(details)

– [Added in TB 64]

Sets the badge text for the action button. The badge is displayed on top of the icon.

Parameters

details

details

(object)

text

text

(string or null)

Any number of characters can be passed, but only about four can fit in the space. Cleared by setting it to null or an empty string.

tabId

[tabId]

(integer, optional)

Sets the badge text only for the given tab.

windowId

[windowId]

(integer, optional) Unsupported.

Will throw an error if used.

setBadgeTextColor(details)

– [Added in TB 128]

Sets the text color for the badge.

Parameters

details

details

(object)

color

color

(string or ColorArray or null)

The color to use as text color in the badge. Cleared by setting it to null.

tabId

[tabId]

(integer, optional)

Sets the text color for the badge only for the given tab.

windowId

[windowId]

(integer, optional) Unsupported.

Will throw an error if used.

setIcon(details)

– [Added in TB 64]

Sets the icon for the action button. Either the path or the imageData property must be specified.

Parameters

details

details

(object)

imageData

[imageData]

The image data for one or more icons for the action button.

path

[path]

(IconPath, optional)

The paths to one or more icons for the action button.

tabId

[tabId]

(integer, optional)

Sets the icon only for the given tab.

windowId

[windowId]

(integer, optional) Unsupported.

Will throw an error if used.

setLabel(details)

– [Added in TB 85]

Sets the label of the action button. Can be used to set different values for the tooltip (defined by the title) and the label. Additionally, the label can be set to an empty string, not showing any label at all.

Parameters

details

details

(object)

label

label

(string or null)

A string the action button should use as its label, overriding the defined title. Can be set to an empty string to not display any label at all. If the containing toolbar is configured to display text only, its title will be used. Cleared by setting it to null.

tabId

[tabId]

(integer, optional)

Sets the label only for the given tab.

windowId

[windowId]

(integer, optional) Unsupported.

Will throw an error if used.

setPopup(details)

– [Added in TB 64]

Sets the html document to be opened as a popup when the user clicks on the action button.

Parameters

details

details

(object)

popup

popup

(string or null)

The html file to show in a popup. Can be set to an empty string to not open a popup. Cleared by setting it to null (popup value defined the manifest will be used).

tabId

[tabId]

(integer, optional)

Sets the popup only for the given tab.

windowId

[windowId]

(integer, optional) Unsupported.

Will throw an error if used.

setTitle(details)

– [Added in TB 64]

Sets the title of the action button. Is used as tooltip and as the label.

Parameters

details

details

(object)

title

title

(string or null)

A string the action button should display as its label and when moused over. Cleared by setting it to null or an empty string (title defined the manifest will be used).

tabId

[tabId]

(integer, optional)

Sets the title only for the given tab.

windowId

[windowId]

(integer, optional) Unsupported.

Will throw an error if used.

Events

onClicked

– [Added in TB 64]

Fired when an action button is clicked. This event will not fire if the action has a popup. This is a user input event handler. For asynchronous listeners some restrictions apply.

Parameters for onClicked.addListener(listener)

listener(tab, info)

listener(tab, info)

A function that will be called when this event occurs.

Parameters passed to the listener function

tab

tab

(Tab)

– [Added in TB 74]

info

[info]

(OnClickData, optional)

– [Added in TB 74]

Types

ColorArray

– [Added in TB 64]

An array of four integers in the range [0,255] that make up the RGBA color. For example, opaque red is [255, 0, 0, 255].

array of integer

ExtensionFileUrl

string

ExtensionURL

A path relative to the root of the extension.

string

IconPath

Either a string to specify a relative path of a single icon to be used for all sizes, or a dictionary object to specify paths for multiple icons in different sizes, so the icon does not have to be scaled for a device with a different pixel density. Each entry is a name-value pair with value being a relative path to an icon file, and name its size. Example:

{
  "16": "icon16.png",
  "32": "icon32.png"
}

See the MDN documentation about choosing icon sizes for more information on this topic.

object

or

ImageDataDictionary

– [Added in TB 90]

A dictionary object to specify multiple ImageData objects in different sizes, so the icon does not have to be scaled for a device with a different pixel density. Each entry is a name-value pair with value being an ImageData object, and name its size.

object

ImageDataType

– [Added in TB 64]

Pixel data for an image. Must be an ImageData object (for example, from a canvas element).

OnClickData

– [Added in TB 74]

Information sent when an action button is clicked.

object

modifiers

modifiers

(array of string)

An array of keyboard modifiers that were held while the menu item was clicked.

Supported values:

Alt

Command

Only available on macOS.

Ctrl

Not available on macOS.

MacCtrl

Only available on macOS, but of limited use in a click event: Holding down the CTRL key while clicking with the mouse is referred to as a ‘CTRL click’ under macOS and is interpreted as a right mouse click. In a default profile the dom.event.treat_ctrl_click_as_right_click.disabled preference is not enabled and the MacCtrl modifier key is not forwarded to the API.

Shift

button

[button]

(integer, optional)

An integer value of button by which menu item was clicked.

ThemeIcons

Define a set of icons for themes depending on whether Thunderbird detects that the theme uses dark or light text. All provided URLs must be relative to the manifest.json file.

object

dark

dark

The dark icon to use for light themes

light

light

A light icon to use for dark themes

size

size

(integer)

The size of the icons