LogoLogo
  • About Thunderbird
  • Contributing to Thunderbird
    • Getting Started Contributing
    • Setting Up A Build Environment
    • Building Thunderbird
      • Windows Build Prerequisites
      • Linux Build Prerequisites
      • macOS Build Prerequisites
      • Artifact Builds
    • Codebase Overview
      • Account Configuration
      • Address Book
      • Chat Core
        • Notifications
        • Message Styles
        • Keyboard shortcuts
        • Chat Core Protocols
        • Contacts
      • Mail Front-End
    • Tutorials and Examples
      • Hello World Example
      • Thunderbird Live Development Videos
    • Fixing a Bug
      • Bug Triaging 101
        • Bug Status Classicification
        • Bug Types
        • Garbage Collection
        • Narrow the Scope
      • Using Mercurial Bookmarks
      • Using Mercurial Queues
      • Lint and Format Code
      • Using ESLint to Format Javascript Code
      • Try Server
      • Landing a Patch
      • Care and Feeding of the Tree
    • Testing
      • Running Tests
      • Adding Tests
      • Writing Mochitest Tests
  • Planning
    • Roadmap
    • Android Roadmap
    • Supported Standards
  • Add-on Development
    • Introduction
    • What's new?
      • Manifest Version 3
    • A "Hello World" Extension Tutorial
      • Using WebExtension APIs
      • Using a Background Page
      • Using Content Scripts
    • A Guide to Extensions
      • Supported Manifest Keys
      • Supported UI Elements
      • Supported WebExtension APIs
      • Thunderbird's WebExtension API Documentation
      • Thunderbird WebExtension Examples
      • Introducing Experiments
    • A Guide to Themes
    • Developer Community
    • Documentation & Resources
      • Tips and Tricks
    • Add-on Update Guides
      • Update for Thunderbird 128
      • Update for Thunderbird 115
        • Adapt to Changes in Thunderbird 103-115
      • Update for Thunderbird 102
        • Adapt to Changes in Thunderbird 92-102
      • Update for Thunderbird 91
        • Adapt to Changes in Thunderbird 79-91
      • Update for Thunderbird 78
        • Adapt to Changes in Thunderbird 69-78
      • Update for Thunderbird 68
        • Adapt to Changes in Thunderbird 61-68
      • How to convert legacy extensions?
        • Convert wrapped WebExtensions to modern WebExtensions
        • Convert legacy WebExtensions to modern WebExtensions
        • Convert legacy overlay extension to legacy WebExtension
        • Convert legacy bootstrapped extension to legacy WebExtension
  • Releases
    • Thunderbird Channels
    • Release Cadence
    • Uplifting Fixes
    • Feature Flags
    • Tracking Fixes for Releases
    • Contributing to Release Notes
Powered by GitBook
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

Was this helpful?

Edit on GitHub
Export as PDF
  1. Add-on Development

A Guide to Themes

How to create themes for Thunderbird.

PreviousIntroducing ExperimentsNextDeveloper Community

Last updated 7 months ago

Was this helpful?

A theme is a Thunderbird add-on that allows to change the appearance of Thunderbird. This document covers the following topics:

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 add-ons. Below is a basic example:

{
  "manifest_version":2,
  "browser_specific_settings":{
    "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"
    }
  }
}

The following manifest keys define basic properties:

  • manifest_version: A mandatory key defining the Manifest version used by the theme. Supported versions are 2 and 3 (since Thunderbird Beta 110). The Manifest defines the basic rules how a theme needs to be crafted and how it can interact with Thunderbird.

  • name : A mandatory key to set the name of the theme.

  • version : A mandatory key to define a number that denotes the version of the theme.

  • description : A brief description of the theme.

  • author : The name of a person or company representing the developer.

The browser_specific_settings.gecko manifest key defines the following properties:

  • strict_min_version: Defines the lowest targeted version of Thunderbird.

  • strict_max_version: Defines the highest targeted version of Thunderbird. It can be set to a specific version or a broader match to limit it to a branch (for example 102.*). Usually not needed.

  • id: The id serves as a unique identifier for the theme and is mandatory in order to upload a theme to ATN or to be able to install it from an XPI file.

Although not required by Firefox, Thunderbird requires anid.Thunderbird does not sign add-ons, and themes will not install without it.

Best practice is to use an "email-address-style" id (but not a real email address) on a domain you control, for example name-of-your-addon@example.com, if you own example.com. As the id of your theme cannot be changed once it is published, it is highly recommended to use a domain that you plan to keep for the forseeable future. If you don't have a domain to use, feel free to use: <atn-user-name>.<add-on-name>@addons.thunderbird.net\

Alternatively, you may use an UUID enclosed in curly braces, for example: {e4aa2097-8ee9-49a4-9ec7-c633b1e8dfda}

Additional theme properties

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",
  "browser_specific_settings": {
    "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

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:

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

Although the above theme will work as-is, there are other properties which can be added. All currently supported properties are listed in the definition in our WebExtension API documentation.

Dynamic themes are actually normal extensions, that use the method of the API instead of a static manifest key. They can set the same theme properties like static themes, but they can change them dynamically. For instance the is a dynamic theme that changes the theme colors based on the time of day.

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 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 API and by loading additional stylesheets to define new CSS variables, extending the theme-able areas of Thunderbird.

Use the to discover CSS selectors for Thunderbird UI elements or internal Thunderbird CSS variables.

Further information regarding theme experiments can be found in our .

Our example repository includes an to change the color of the chat icon.

ThemeType
update()
theme
theme
Night and Day theme
A Guide to Extensions
messageDisplayScripts.register()
composeScripts.register()
theme
theme
browser toolbox
WebExtension API documentation of the theme API
add-on using a theme experiment
Static Themes
Dynamic Themes
Theming of message-compose-windows and message-display-tabs
Theme Experiments