↑ arvau

MDN / theme

Use the theme key to define a static theme to apply to Firefox. When provided alone, this defines the theme used when Firefox is using either the light or dark color schemes. If the dark_theme key key is provided, this key provides the theme used when Firefox is using the light color scheme.

If you want to include a theme with an extension, please see the API.

Since May 2019, themes need to be signed to be installed (Firefox bug 1545109). See Signing and distributing your add-on for more details.

Image formats

The following image formats are supported in all theme image properties:

  • JPEG

  • PNG

  • APNG

  • SVG (animated SVG is supported from Firefox 59)

  • GIF (animated GIF isn’t supported)

Syntax

The theme key is an object that takes the following properties:

images

All URLs are relative to the manifest.json file and cannot reference an external URL.

Images should be 200 pixels high to ensure they always fill the header space vertically.

CSS gradient syntax

A CSS gradient is specified as an object in the form { "GRADIENT_TYPE": "GRADIENT_PARAMS" }, where:

  • GRADIENT_TYPE is one of:

    • linear-gradient

    • radial-gradient

    • conic-gradient

    • repeating-linear-gradient

    • repeating-radial-gradient

    • repeating-conic-gradient

    GRADIENT_PARAMS contains the parameters for that CSS gradient function, as described in CSS gradient values.

colors

These properties define the colors used for different parts of the browser. They are all optional. How these properties affect the Firefox UI is shown here:

Where a component is affected by multiple color properties, the properties are listed in order of precedence.

All these properties can be specified as either a string containing any valid CSS color string (including hexadecimal), or an RGB array, such as "tab_background_text": [ 107 , 99 , 23 ].

In Chrome, colors may only be specified as RGB arrays.

Aliases

Additionally, this key accepts various properties that are aliases for one of the properties above. These are provided for compatibility with Chrome. If an alias is given, and the non-alias version is also given, then the value will be taken from the non-alias version.

properties

Examples

A basic theme must define an image to add to the header, the accent color to use in the header, and the color of text used in the header:

 "theme": {
   "images": {
     "theme_frame": "images/sun.jpg"
   },
   "colors": {
     "frame": "#CF723F",
     "tab_background_text": "black"
   }
 }

Multiple items can be used to fill the header. Before Firefox version 60, use a blank or transparent header image to gain control over the placement of each additional item:

 "theme": {
   "images": {
     "additional_backgrounds": [ "images/left.png", "images/middle.png", "images/right.png"]
   },
   "properties": {
     "additional_backgrounds_alignment": [ "left top", "top", "right top"]
   },
   "colors": {
     "frame": "blue",
     "tab_background_text": "white"
   }
 }

You can also fill the header with a repeated image, or images, in this case a single image anchored in the middle top of the header and repeated across the rest of the header:

 "theme": {
   "images": {
     "additional_backgrounds": [ "images/logo.png"]
   },
   "properties": {
     "additional_backgrounds_alignment": [ "top" ],
     "additional_backgrounds_tiling": [ "repeat"  ]
   },
   "colors": {
     "frame": "green",
     "tab_background_text": "black"
   }
 }

The following example uses most of the different values for theme.colors:

  "theme": {
    "images": {
      "theme_frame": "weta.png"
    },

    "colors": {
       "frame": "darkgreen",
       "tab_background_text": "white",
       "toolbar": "blue",
       "bookmark_text": "cyan",
       "toolbar_field": "orange",
       "toolbar_field_border": "white",
       "toolbar_field_text": "green",
       "toolbar_top_separator": "red",
       "toolbar_bottom_separator": "white",
       "toolbar_vertical_separator": "white"
    }
  }

It will give you a browser that looks like this:

A browser window with two open tabs and dark green background color in the header area. The inactive tab has a white text color. The active tab and the toolbar have a blue background color with cyan-colored text. The URL bar has an orange background with white borders, a green text color and a white-colored vertical line separator. A red-colored line is used to separate the tabs on the top and a white line to separate the tabs from the content below them.

In this screenshot, "toolbar_vertical_separator" is the white vertical line in the URL bar dividing the Reader Mode icon from the other icons.

This example (Firefox 153+) mixes image backgrounds with a CSS linear gradient:

"theme": {
  "images": {
    "additional_backgrounds": [
      "background-image1.svg",
      "background-image2.svg",
      { "linear-gradient": "to bottom, #FF6BBA -20%, #FFC999 50%" }
    ]
  },
  "properties": {
    "additional_backgrounds_alignment": ["right top", "left top", "right top"],
    "additional_backgrounds_tiling": ["no-repeat", "no-repeat", "repeat-x"],
    "additional_backgrounds_size": ["auto", "auto", "auto 144px"]
  }
}

This results in:

  • background-image1.svg displaying at the top right, at its natural size.

  • background-image2.svg displaying at the top left, at its natural size.

  • The linear-gradient displaying from the top right, tiled horizontally across the header (repeat-x), and sized to 144px tall (width is automatic). The gradient transitions from pink (#FF6BBA) at the top to peach (#FFC999) at the bottom.

Browser compatibility

Chrome compatibility

In Chrome:

  • colors/toolbar_text isn’t used, use colors/bookmark_text instead.

  • images/theme_frame anchors the image to the top left of the header and if the image doesn’t fill the header area tile the image.

  • all colors must be specified as an array of RGB values, like this:

    "theme": {
  "colors": {
     "frame": [255, 0, 0],
     "tab_background_text": [0, 255, 0],
     "bookmark_text": [0, 0, 255]
  }
}

    From Firefox 59 onward, both the array form and the CSS color form are accepted for all properties. Before that, colors/frame and colors/tab_background_text required the array form, while other properties required the CSS color form.