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​

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":"mytheme@sample.themes.thunderbird.net",
      "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.

Additional color properties

Although the above theme will work as-is, there are other properties which can be added.

For the colors object, there are many options. Those known to work are listed below:

• bookmark_text

• frame

• frame_inactive

• popup

• popup_text

• popup_border

• popup_highlight

• popup_highlight_text

• popup_border

• sidebar

• sidebar_text

• sidebar_highlight

• sidebar_highlight_text

• sidebar_border

• tab_text

• tab_line

• tab_loading

• tab_background_text

• toolbar_field

• toolbar_field_text

• toolbar_field_highlight

• toolbar_field_highlight_text

• toolbar_field_border

• toolbar_field_focus

• toolbar_field_text_focus

• toolbar_field_border_focus

• toolbar_top_separator

• toolbar_bottom_separator

• toolbar_vertical_separator

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": "nuvola@paenglab.ch",
      "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 MailExtensions, that use the theme API instead of a theme manifest key. They can set the same theme properties like static themes, but they can change them dynamically. For instance, one example used in the Firefox documentation is a dynamic theme that changes the theme colors based on the time of day.

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

The default theming properties do not support the Thunderbird specific 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"} ]
});