Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
152 lines (131 sloc) 3.73 KB
How to create themes using WebExtensions.

WebExtension Themes

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.

{% hint style="danger" %} 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. {% endhint %}

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": "",
      "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"
You can’t perform that action at this time.