theme API
The theme API allows for customization of Thunderbird’s visual elements.
Manifest file properties
theme_experiment
A theme experiment allows modifying the user interface of Thunderbird beyond what is currently possible using the built-in color, image and property keys of ThemeType. These experiments are a precursor to proposing new theme features for inclusion in Thunderbird. Experimentation is done by mapping internal CSS color, image and property variables to new theme keys and using them in ThemeType and by loading additional style sheets to add new CSS variables, extending the theme-able areas of Thunderbird. Can be used in static and dynamic themes.
Permissions
The following permissions influence the behavior of the API. Depending on which permissions are requested, additional methods might be available, or certain data may be included in responses.
Hint
Request permissions only when needed. Unnecessary requests may result in rejection during ATN review.
theme
Grant access to some or all methods of the theme API.
Functions
getCurrent([windowId])
– [Added in TB 86]
Returns the current theme for the specified window or the last focused window.
reset([windowId])
– [Added in TB 86]
Removes the updates made to the theme.
Parameters
windowId
The id of the window to reset. No id resets all windows.
Required permissions
update([windowId], details)
– [Added in TB 86]
Make complete updates to the theme. Resolves when the update has completed.
Parameters
windowId
The id of the window to update. No id updates all windows.
details
Required permissions
Events
onUpdated
– [Added in TB 86]
Fired when a new theme has been applied
Parameters for onUpdated.addListener(listener)
listener(updateInfo)
A function that will be called when this event occurs.
Parameters passed to the listener function
updateInfo
Details of the theme update
Types
ExtensionURL
A path relative to the root of the extension.
string
ImageDataOrExtensionURL
Defines an image resource. Either a image URL relative the the extensions manifest.json file (supported image formats are JPEG, PNG, APNG, SVG and GIF), or a data URL using a base64 encoded representation of a PNG or JPEG image.
Example for a base64 encoded PNG image:
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==
string
ThemeColor
– [Added in TB 86]
Defines a color value.
string
A string containing a valid CSS color string, including hexadecimal or functional representations. For example the color crimson can be specified as:
crimson
#dc143c
rgb(220, 20, 60) (or rgba(220, 20, 60, 0.5) to set 50% opacity)
hsl(348, 83%, 47%) (or hsla(348, 83%, 47%, 0.5) to set 50% opacity)
or
array of integer
An RGB array of 3 integers. For example [220, 20, 60] for the color crimson.
or
array of number
An RGBA array of 3 integers and a fractional (a float between 0 and 1). For example [220, 20, 60, 0.5] for the color crimson with 50% opacity.
ThemeExperiment
– [Added in TB 86]
Defines additional color, image and property keys to be used in ThemeType, extending the theme-able areas of Thunderbird.
object
colors
A dictionary object with one or more key-value pairs to map new theme color keys to internal Thunderbird CSS color variables. The new color key is usable as a color reference in ThemeType.
The following example maps the theme color key popup_affordance to the CSS variable –arrowpanel-dimmed:
{
"popup_affordance": "--arrowpanel-dimmed"
}
images
A dictionary object with one or more key-value pairs to map new theme image keys to internal Thunderbird CSS image variables. The new image key is usable as an image reference in ThemeType.
The following example maps the theme image key theme_toolbar to the CSS variable –toolbar-bgimage:
{
"theme_toolbar": "--toolbar-bgimage"
}
properties
A dictionary object with one or more key-value pairs to map new theme property keys to internal Thunderbird CSS property variables. The new property key is usable as a property reference in ThemeType.
The following example maps the theme property key toolbar_image_alignment to the CSS variable –toolbar-bgalignment:
{
"toolbar_image_alignment": "--toolbar-bgalignment"
}
stylesheet
URL to a stylesheet introducing additional CSS variables, extending the theme-able areas of Thunderbird.
The theme_experiment add-on in our example repository is using the stylesheet shown below, to add the –chat-button-color CSS variable:
image.toolbarbutton-icon[label="Chat"] {
fill: var(--chat-button-color);
}
The following manifest.json file maps the –chat-button-color CSS variable to the theme color key exp_chat_button and uses it to set a color for the chat button:
{
"name": "Theme Experiment",
"description": "Changing the color of the chat icon using a theme_experiment.",
"version": "1",
"applications": {
"gecko": {
"id": "[email protected]",
"strict_min_version": "78.0"
}
},
"manifest_version": 2,
"theme_experiment": {
"stylesheet": "style.css",
"colors": {
"exp_chat_button": "--chat-button-color"
}
},
"theme": {
"colors": {
"exp_chat_button": "orange"
}
}
}
ThemeManifest
– [Added in TB 86]
Contents of manifest.json for a static theme
object
theme
Properties for a static theme. A static theme must not contain any other WebExtension logic. If additional logic is required, request the permission and load/update the theme dynamically. More information about themes can be found in the theme guide
dark_theme
Fallback properties for the dark system theme in a static theme.
default_locale
icons
Icons shown in the Add-ons Manager.
theme_experiment
CSS file with additional styles.
ThemeType
– [Added in TB 86]
Contains the color, image and property settings of a theme.
object
colors
A dictionary object with one or more key-value pairs to map color values to theme color keys. The following built-in theme color keys are supported:
accentcolor
bookmark_text
Not used in Thunderbird.
button_background_active
The color of the background of the pressed toolbar buttons.
button_background_hover
The color of the background of the toolbar buttons on hover.
frame
The background color of the header area.
frame_inactive
The background color of the header area when the window is inactive.
icons
The color of the toolbar icons. Defaults to the color specified by toolbar_text.
icons_attention
The color of the toolbar icons in attention state such as the chat icon with new messages.
ntp_background
Not used in Thunderbird.
ntp_text
Not used in Thunderbird.
popup
The background color of popups such as the AppMenu.
popup_border
The border color of popups.
popup_highlight
The background color of items highlighted using the keyboard inside popups.
popup_highlight_text
The text color of items highlighted using the keyboard inside popups.
popup_text
The text color of popups.
sidebar
The background color of the trees.
sidebar_border
The border color of the trees.
sidebar_highlight
The background color of highlighted rows in trees.
sidebar_highlight_border
The border color of highlighted rows in trees.
sidebar_highlight_text
The text color of highlighted rows in trees.
sidebar_text
The text color of the trees. Needed to enable the tree theming.
tab_background_separator
The color of the vertical separator of the background tabs.
tab_background_text
The text color of the unselected tabs.
tab_line
The color of the selected tab line.
tab_loading
The color of the tab loading indicator.
tab_selected
Background color of the selected tab. Defaults to the color specified by toolbar.
tab_text
The text color for the selected tab. Defaults to the color specified by toolbar_text.
textcolor
toolbar
The background color of the toolbars. Also used as default value for tab_selected.
toolbar_bottom_separator
The color of the line separating the bottom of the toolbar from the region below.
toolbar_field
The background color for fields in the toolbar, such as the search field.
toolbar_field_border
The border color for fields in the toolbar.
toolbar_field_border_focus
The focused border color for fields in the toolbar.
toolbar_field_focus
The focused background color for fields in the toolbar.
toolbar_field_highlight
The background color used to indicate the current selection of text in the search field.
toolbar_field_highlight_text
The color used to draw text that’s currently selected in the search field.
toolbar_field_separator
Not used in Thunderbird.
toolbar_field_text
The text color for fields in the toolbar.
toolbar_field_text_focus
The text color in the focused fields in the toolbar.
toolbar_text
The text color in the main Thunderbird toolbar. Also used as default value for icons and tab_text.
toolbar_top_separator
The color of the line separating the top of the toolbar from the region above.
toolbar_vertical_separator
The color of the vertical separators on the toolbars.
images
A dictionary object with one or more key-value pairs to map images to theme image keys. The following built-in theme image keys are supported:
additional_backgrounds
Additional images added to the header area and displayed behind the theme_frame image.
headerURL
theme_frame
Foreground image on the header area.
properties
A dictionary object with one or more key-value pairs to map property values to theme property keys. The following built-in theme property keys are supported:
additional_backgrounds_alignment
Supported values:
bottom
center
center bottom
center center
center top
left
left bottom
left center
left top
right
right bottom
right center
right top
top
additional_backgrounds_tiling
Supported values:
no-repeat
repeat
repeat-x
repeat-y
color_scheme
content_color_scheme
ThemeUpdateInfo
– [Added in TB 86]
Info provided in the onUpdated listener.