composeAction

The browserAction and composeAction APIs first appeared in Thunderbird 64. They are very similar to Firefox’s browserAction API.

Use a composeAction to put an icon in the message composition toolbars. In addition to its icon, a composeAction can also have a tooltip, a badge, and a popup.

Manifest file properties

[compose_action]

(object)

[browser_style]

(boolean)

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

[default_area]

(string)

Defines the location the composeAction will appear by default. The default location is maintoolbar.

Supported values:

maintoolbar

formattoolbar

[default_icon]

The icon for the messageDisplayAction.

[default_label]

(string)

– [Added in TB 84.0b3, backported to TB 78.6.1]

The label of the composeAction, 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]

(string)

The html document to be opened as a popup when the user clicks on the composeAction’s icon.

[default_title]

(string)

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

[theme_icons]

(array of ThemeIcons)

Specifies icons to use for dark and light themes

Note

A manifest entry named compose_action is required to use composeAction.

Functions

setTitle(details)

Sets the title of the composeAction. This shows up in the tooltip and the label. Defaults to the add-on name.

Parameters

details

(object)

title

(string or null)

The string the composeAction should display as its label and when moused over.

getTitle(details)

Gets the title of the composeAction.

Parameters

details

Return type (Promise)

string

setLabel(details)

– [Added in TB 84.0b3, backported to TB 78.6.1]

Sets the label of the composeAction, 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.

Parameters

details

(object)

label

(string or null)

The string the composeAction should use as label. 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.

getLabel(details)

– [Added in TB 84.0b3, backported to TB 78.6.1]

Gets the label of the composeAction.

Parameters

details

Return type (Promise)

string

setIcon(details)

Sets the icon for the composeAction. The icon can be specified either as the path to an image file or as the pixel data from a canvas element, or as dictionary of either one of those. Either the path or the imageData property must be specified.

Parameters

details

(object)

Either an ImageDataType object defining a single icon used for all sizes or an ImageDataDictionary object defining dedicated icons for different sizes.

[path]

(string or IconPathDictionary)

Either a relative image path defining a single icon used for all sizes or an IconPathDictionary object defining dedicated icons for different sizes.

setPopup(details)

Sets the html document to be opened as a popup when the user clicks on the composeAction’s icon.

Parameters

details

(object)

popup

(string or null)

The html file to show in a popup. If set to the empty string (‘’), no popup is shown.

getPopup(details)

Gets the html document set as the popup for this composeAction.

Parameters

details

Return type (Promise)

string

setBadgeText(details)

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

Parameters

details

(object)

text

(string or null)

Any number of characters can be passed, but only about four can fit in the space.

getBadgeText(details)

Gets the badge text of the composeAction. If no tab nor window is specified, the global badge text is returned.

Parameters

details

Return type (Promise)

string

setBadgeBackgroundColor(details)

Sets the background color for the badge.

Parameters

details

(object)

color

(string or ColorArray or null)

An array of four integers in the range [0,255] that make up the RGBA color of the badge. For example, opaque red is [255, 0, 0, 255]. Can also be a string with a CSS value, with opaque red being #FF0000 or #F00.

getBadgeBackgroundColor(details)

Gets the background color of the composeAction.

Parameters

details

Return type (Promise)

enable([tabId])

Enables the composeAction for a tab. By default, a composeAction is enabled.

Parameters

[tabId]

(integer)

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

disable([tabId])

Disables the composeAction for a tab.

Parameters

[tabId]

(integer)

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

isEnabled(details)

Checks whether the composeAction is enabled.

Parameters

details

Return type (Promise)

boolean

openPopup()

Opens the extension popup window in the active window.

Events

onClicked

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

Parameters for onClicked.addListener(listener)

listener(tab, info)

A function that will be called when this event occurs.

Parameters passed to the listener function

tab

(Tab)

– [Added in TB 74.0b2]

[info]

– [Added in TB 74.0b2]

Types

ColorArray

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

Details

Specifies to which tab or window the value should be set, or from which one it should be retrieved. If no tab nor window is specified, the global value is set or retrieved.

object

[tabId]

(integer)

When setting a value, it will be specific to the specified tab, and will automatically reset when the tab navigates. When getting, specifies the tab to get the value from; if there is no tab-specific value, the window one will be inherited.

[windowId]

(integer)

When setting a value, it will be specific to the specified window. When getting, specifies the window to get the value from; if there is no window-specific value, the global one will be inherited.

ImageDataDictionary

A {size: ImageDataType} dictionary representing the icon to be set. The actual ImageDataType to be used is chosen depending on the screen’s pixel density. See the MDN documentation on browser styles for more information on this. At least one ImageDataType must be specified.

object

ImageDataType

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

OnClickData

– [Added in TB 74.0b2]

Information sent when a compose action is clicked.

object

modifiers

(array of string)

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

Supported values:

Shift

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.

[button]

(integer)

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

External Types

The following types are not defined by this API, but by the underlying Mozilla WebExtension code base. They are included here, because there is no other public documentation available.

IconPathDictionary

A {size: path} dictionary representing the icon to be set. The actual image to be used is chosen depending on the screen’s pixel density. See the MDN documentation about choosing icon sizes for more information on this. At least one icon must be specified. Example:

{
  "48": "icon48.png",
  "96": "icon96.png"
}

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

(string)

A URL pointing to an icon. This icon displays when a theme using dark text is active (such as the Light theme, and the Default theme if no default_icon is specified).

light

(string)

A URL pointing to an icon. This icon displays when a theme using light text is active (such as the Dark theme).

size

(integer)

The size of the two icons in pixels, for example 16 or 32.