Themes developed using the WebExtensions API in Firefox enable you to change the look of the browser by adding images to the header area of the Firefox browser; this is the area behind the menu bar, toolbars, address bar, search bar, and tab strip.

These theme options can be implemented as static themes (although the theme images themselves may be animated) or as dynamic themes created in a browser extension.

Static themes

Static themes are specified using the same resources as a browser extension: a manifest.json file to define the theme components with those components stored in the same folder as the manifest.json file or a sub folder. These resources are then packed in a zip for publication on addons.mozilla.org (AMO) or for self-distribution. For more information on self-distribution, visit Signing and distributing your add-on.

You can also use the theme generator on AMO to create a static theme. Additionally, Firefox Color can be used to preview customizations to the browser's theme with options to share and export a theme.

Defining a theme

To create a theme (in this example a simple, single image theme):

• Create a folder in a suitable location on your computer.
• Add the theme image file to the folder:

  <mytheme>
   <your_header_image>.<type>

• Create a file called manifest.json in the folder and edit its content as follows:

  {
    "manifest_version": 2,
    "version": "1.0",
    "name": "<your_theme_name>",
    "theme": {
      "images": {
        "theme_frame": "<your_header_image>.<type>"
      },
      "colors": {
        "frame": "#FFFFFF",
        "tab_background_text": "#000"
      }
    }
  }
  

  Where:
  • "frame": is the heading area background color for your theme.
  • "tab_background_text": the color of the text in the heading area.
• Package your theme and submit it to AMO, following these instructions. Themes can be submitted to AMO for hosting or for self-distribution.

Static theme approaches

There are two approaches you can take to theming the header area of Firefox: using a single image or using multiple images. You could combine the two, but it’s easier to treat them separately.

Single image themes

This is the basic or minimal theming option, where you define:

• a single image, which is anchored to the top right of the header area.
• A color for the text in the header.

The area your header image needs to fill is a maximum of 200 pixels high. The maximum image width is determined by the resolution of the monitor Firefox is displaying on and how much of the monitor Firefox is using. Practically, this means you would need to allow for a width of up to 5120 pixels wide (for the next generation of 5k monitors). However, rather than creating a very wide image, a better approach is to use a narrower image with a transparent left edge so that it fades to the background color. For example, we could use this image

combined with a complementary background color, to create this effect in the header

See details about this theme in the themes example weta_fade.

Obviously, you can still provide a single wide image if you prefer.

Multiple image themes

As an alternative to creating a single image theme, you have the option to use multiple images. These images can be individually anchored to locations within the header, with the option to apply tiling to each image.

Depending on the effect you want to create you may need to suppress the mandatory "theme_frame": image with an empty or transparent image. You would use an empty or transparent image if, for example, you wanted to tile a centrally justified image, such as

to create this effect

Here you specify the weta image like this:

"images": {
  "theme_frame": "empty.png",
  "additional_backgrounds": [ "weta_for_tiling.png"]
},

and the images tiling with:

"properties": {
  "additional_backgrounds_alignment": [ "top" ],
  "additional_backgrounds_tiling": [ "repeat"  ]
},

Full details of how to setup this theme can be found in the themes example weta_tiled. Full detais of the alignment and tiling options can be found in the "theme" key description.

Alternatively, you can use multiple images, say combining the original weta image with this one anchored to the left of the header

to create this effect

Where the images are specified with:

"images": {
  "theme_frame": "empty.png",
  "additional_backgrounds": [ "weta.png", "weta-left.png"]
},

and their alignment by:

"properties": {
  "additional_backgrounds_alignment": [ "right top" , "left top" ]
},

Full details of how to setup this theme can be found in the themes example weta_mirror. Full details of the alignment options can be found in the "theme" key description.

Static animated themes

It is possible to create an animated theme using an APNG format image, as in the themes example animated. However, remember that rapid animations, such as the one in the example might be too distracting for a practical theme.

You can also animate themes programmatically, which we discuss in Dynamic themes.

Updating static themes

If your static theme is hosted on AMO, you can upload a new version using the Developer Hub with the following steps:

1. Visit the product page for your theme through the Developer Hub
2. Select "Upload New Version" on the left
3. Upload your packaged file for validation or modify it using the theme generator

For self-hosted static themes, a new version can be updated through AMO by following the above steps or be handled by you through an updateURL or external application updates. A new version will need to be signed through the Developer Hub.

Dynamic themes

As an alternative to defining a static theme, you can use the theme API to control the theme used in Firefox from within a browser extension. There are a couple of use cases for this option:

• To bundle a theme with a browser extension, as an added extra.
• Create a dynamic theme that changes under programmatic control.

And, obviously, you can combine the two and bundle a programmatically controlled theme with your extension.

Using the theme API is straightforward. First, request "theme" permission in the extension's manifest.json file. Next, you build a JSON object containing the same information you would use in a static theme’s manifest.json, Finally, pass the JSON object in a theme.update() call.

For example, the following code, from the dynamic theme example defines the content for the day and night elements of the dynamic theme:

const themes = {
  'day': {
    images: {
     theme_frame: 'sun.jpg',
    },
    colors: {
     frame: '#CF723F',
     tab_background_text: '#111',
    }
  },
  'night': {
    images: {
     theme_frame: 'moon.jpg',
    },
    colors: {
     frame: '#000',
     tab_background_text: '#fff',
    }
  }
};

The theme.Theme object is then passed to theme.update() to change the header theme, as in this code snippet from the same example:

function setTheme(theme) {
  if (currentTheme === theme) {
    // No point in changing the theme if it has already been set.
    return;
  }
  currentTheme = theme;
  browser.theme.update(themes[theme]);
}

Learn more about dynamic themes and see an additional example in the following video:

If you have not built a browser extension before, check out Your first extension for a step-by-step guide.

Cross-browser compatibility

There is currently limited compatibility between themes in the major browsers. Opera takes an entirely different approach, and Microsoft Edge themes are not yet open to developers.

There is good compatibility between Firefox static themes and Chrome themes, providing the ability to port a single header image theme from Firefox to Chrome. However, noting that "frame": and "tab_background_text": only support RGB color array definition on Chrome.

So, in the single image theme example (weta_fade) could be supported in Chrome using the following manifest.json file:

{
  "manifest_version": 2,
  "version": "1.0",
  "name": "<your_theme_name>",
  "theme": {
    "images": {
      "theme_frame": "weta.png"
    },
    "colors": {
      "frame": [ 173 , 176 , 159 ],
      "tab_background_text": [ 0 , 0 , 0 ]
    }
  }
}

Also, note that Chrome tiles the “theme_frame”: image from the left of the header area.

For more information, see the notes on Chrome compatibility.