A Guide to Themes

A Theme is a Thunderbird add-on that allows to change the appearance of Thunderbird. This document covers the following topics:
​Static Themes​
​Dynamic Themes​
​Theming of message-compose-windows and message-display-tabs​
​Theme Experiments​
Static Themes
Static themes, like the name implies - are static and do not change. They have a set of colors or images that make up the theme and this does not change. It typically consists of two files, zipped up with an .xpi extension just as any other add-on:
manifest.json
image.png or .jpg
The manifest.json file
You must prepare a JSON manifest, named manifest.json just as with other WebExtensions. Below is a basic example:
{
  "manifest_version":2,
  "applications":{
    "gecko":{
      "id":"[email protected]",
      "strict_min_version":"60.0"
    }
  },
  "name":"Thunderbird ExampleTheme",
  "description":"Static theme version of an example Thunderbird theme.",
  "version":"1.0",
  "theme":{
    "images":{
      "theme_frame":"thunderbirdimage.jpg"
    },
    "colors":{
      "frame":"#000000",
      "tab_background_text":"#ffffff"
    }
  }
}
manifest_version is always 2.
id is a unique GUID for your theme.
Although not required by Firefox, Thunderbird requires an applications object with an id set for the add-on! Because we don't sign add-ons, themes will not install without it.
Additional theme properties
Although the above theme will work as-is, there are other properties which can be added. All currently supported properties are listed in the ThemeType definition in our WebExtension API documentation.
Icons
You can add an icon for your theme, like other types of add-ons, with the following code:
  "icons": {
    "16": "icon.png"
  },
Don't forget to put the icon.png file in your add-on as well.
A complete example
Here is a manifest.json from a Theme that uses all the above features, thanks to Paenglab:
{
  "manifest_version": 2,
  "name": "Nuvola WebExtension theme",
  "version": "1.1",
  "applications": {
    "gecko": {
      "id": "[email protected]",
      "strict_min_version": "60.0"
    }
  },
  "description": "Light theme with some gradients.",
  "icons": {
    "16": "icon.png"
  },
  "theme": {
    "colors": {
      "frame": "#e7e8ec",
      "tab_text": "#000",
      "tab_line": "#1f9afd",
      "tab_loading": "#1f9afd",
      "tab_background_text": "#000",
      "bookmark_text": "#333",
      "toolbar_field": "#f2f2f2",
      "toolbar_field_text": "#444",
      "toolbar_field_highlight": "#1f9afd",
      "toolbar_field_highlight_text": "#fff",
      "toolbar_field_border": "#999",
      "toolbar_field_focus": "#f2f2f2",
      "toolbar_field_text_focus": "#000",
      "toolbar_field_border_focus": "#1f9afd",
      "toolbar_top_separator": "#aaa",
      "toolbar_bottom_separator": "#888",
      "toolbar_vertical_separator": "#888",
      "sidebar": "#fbfbfb",
      "sidebar_text": "#000",
      "sidebar_highlight": "rgba(11,113,220,.6)",
      "sidebar_highlight_text": "#fff",
      "sidebar_border": "#999",
      "popup": "#e6e8ef",
      "popup_text": "#000",
      "popup_border": "#666",
      "popup_highlight": "#1f9afd",
      "popup_highlight_text": "#fff"
    },
    "images": {
      "theme_frame": "background.png"
    }
  }
}
Dynamic Themes
Dynamic themes are actually normal MailExtensions, that use the update() method of the theme API instead of a static theme manifest key. They can set the same theme properties like static themes, but they can change them dynamically. For instance the Night and Day theme is a dynamic theme that changes the theme colors based on the time of day.
A Guide to MailExtensions
Theming message-compose-windows and message-display-tabs
The built-in theming properties do not modify the message-compose-windows and the message-display-tabs. These can be manipulated by injecting CSS files using the following WebExtension API methods:
​messageDisplayScripts.register()​
​composeScripts.register()​
To inject the file compose.css into the message-compose-window, register it in your background script as follows:
messenger.composeScripts.register({
  css : [ { file: "compose.css"} ]
});
Theme Experiments
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 the theme API. These experiments are a precursor to proposing new theme features for inclusion in Thunderbird. 
Experimentation is done by exposing already existing internal CSS variables (e.g. --arrowpanel-dimmed) to the theme API and by loading additional stylesheets to define new CSS variables, extending the theme-able areas of Thunderbird.
Use the browser toolbox to discover CSS selectors for Thunderbird UI elements or internal Thunderbird CSS variables.
Further information regarding theme experiments can be found in our WebExtension API documentation of the theme API.
Our example repository includes an add-on using a theme experiment to change the color of the chat icon.
​

Introducing Experiments

Next - Add-on Development

Tips and Tricks

Last modified 1yr ago

Export as PDF

Copy link

Edit on GitHub

On this page

Static Themes

The manifest.json file

Additional theme properties

Icons

A complete example

Dynamic Themes

Theming message-compose-windows and message-display-tabs

Theme Experiments