WebExtension Themes

How to create themes using WebExtensions.

A WebExtension Theme is a Thunderbird add-on that allows you to change cosmetic elements much like the old lightweight themes, but with more functionality.

It typically consists of two files, zipped up with a .xpi extension just as any other add-on:

  • manifest.json

  • image.png or .jpg

Use a manifest.json file

You must prepare a JSON manifest, named "manifest.json" just as with other Web Extensions. Below is a basic example:

"name":"Thunderbird ExampleTheme",
"description":"Static theme version of an example Thunderbird theme.",
  • 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 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


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"