Type Object
Mandatory No
Example
"theme": {
  "images": {
    "headerURL": "images/sun.jpg"
  },
  "colors": {
    "accentcolor": "#CF723F",
    "textcolor": "#000"
  }
}

Use the theme key to define a static theme to apply to Firefox.

If your manifest.json file includes the theme key, the extension is assumed to be a theme and any other WebExtension keys are ignored. If you want to include a theme with an extension, please see the theme API.

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:

Name Type Description
images Object

Mandatory.

A JSON object whose properties represent the images to display in various parts of the browser. See images for details on the properties that this object can contain.

colors Object

Mandatory.

A JSON object whose properties represent the colors of various parts of the browser. See colors for details on the properties that this object can contain.

properties Object

Optional

This object has two properties that affect how the "additional_backgrounds" images are displayed. See properties for details on the properties that this object can contain.

  • "additional_backgrounds_alignment": an array of enumeration values defining the alignment of the corresponding "additional_backgrounds": array item.
    The alignment options include: "bottom", "center", "left", "right", "top", "center bottom", "center center", "center top", "left bottom", "left center", "left top", "right bottom", "right center", and "right top". If not specified, defaults to "left top".
    Optional
  • "additional_backgrounds_tiling": an array of enumeration values defining how the corresponding "additional_backgrounds": array item repeats, with support for "no-repeat", "repeat", "repeat-x", and "repeat-y". If not specified, defaults to "no-repeat".
    Optional

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.

Name Type Description
headerURL String

Mandatory.

The URL of a foreground image to be added to the header area and anchored to the upper right corner of the header area.

Has the following properties:

  • "headerURL": or (optionally, for Chrome compatibility) "theme_frame": the URL of a foreground image to be added to the header area and anchored to the upper right corner of the header area.
    Mandatory.
  • "additional_backgrounds":
    Optional.
theme_frame String

Optional.

Alias for headerURL, provided for Chrome compatibility.

additional_backgrounds Array of String

Optional.

An array of URLs for additional background images to be added to the header area and displayed behind the "headerURL": image. These images layer the first image in the array on top, the last image in the array at the bottom.

By default all images are anchored to the upper right corner of the header area, but their alignment and repeat behavior can be controlled by properties of "properties":.

colors

These properties define the colors used for different parts of the browser. They are all optional except "accentcolor" and "textcolor".

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_text": [ 107 , 99 , 23 ]. But note that in Chrome, colors may only be specified as an RGB array.

See the example screenshot below to understand the parts of the browser UI that are affected by these properties.

Name Description
accentcolor The color of the header area background, displayed in the part of the header not covered or visible through the images specified in "headerURL" and "additional_backgrounds".
background_tab_text The same as "textcolor", provided for Chrome compatibility.
bookmark_text

The same as "toolbar_text", provided for Chrome compatibility.

If this property and "toolbar_text" are both given, then the value for "toolbar_text" will be used.

button_background_active The color of the background of the pressed toolbar buttons.
button_background_hover The color of the background of the toolbar buttons on hover.
frame The same as "accentcolor", provided for Chrome compatibility.
frame_inactive The same as "accentcolor", but only applied to inactive windows, provided for Chrome compatibility.
icons The color of toolbar icons.
icons_attention The color of toolbar icons in attention state such as the starred bookmark icon or finished download icon.
tab_loading The color of the tab loading indicator and the tab loading burst.
tab_text

From Firefox 59, it represents the color of the selected tab.

From Firefox 55 to 58, it is the same as "textcolor", provided for Chrome compatibility.

textcolor The color of the text displayed in the header area.
toolbar The background color for the navigation bar, the bookmarks bar, and the selected tab.
toolbar_bottom_separator The color of the line separating the bottom of the toolbar from the region below.
toolbar_field The background color for fields in the toolbar, such as the URL bar.
toolbar_field_border The border color for fields in the toolbar.
toolbar_field_text The color of text in fields in the toolbar, such as the URL bar.
toolbar_field_separator The color of separators inside the URL bar (previously named toolbar_vertical_separator).
toolbar_text The color of toolbar text.
toolbar_top_separator The color of the line separating the top of the toolbar from the region above.

properties

Name Type Description
additional_backgrounds_alignment

Array of String

Optional.

An array of enumeration values defining the alignment of the corresponding "additional_backgrounds": array item.
The alignment options include:

  • "bottom"
  • "center"
  • "left"
  • "right"
  • "top"
  • "center bottom"
  • "center center"
  • "center top"
  • "left bottom"
  • "left center"
  • "left top"
  • "right bottom"
  • "right center"
  • "right top".

If not specified, defaults to "left top".

additional_backgrounds_tiling

Array of String

Optional.

An array of enumeration values defining how the corresponding "additional_backgrounds": array item repeats. Options include:

  • "no-repeat"
  • "repeat"
  • "repeat-x"
  • "repeat-y"

If not specified, defaults to "no-repeat".

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": {
     "headerURL": "images/sun.jpg"
   },
   "colors": {
     "accentcolor": "#CF723F",
     "textcolor": "#000"
   }
 }

Multiple images can be used to fill the header, using a blank/transparent header image to gain control over the placement of each visible image:

 "theme": {
   "images": {
     "headerURL": "images/blank.png",
     "additional_backgrounds": [ "images/left.png" , "images/middle.png", "images/right.png"]
   },
   "properties": {
     "additional_backgrounds_alignment": [ "left top" , "top", "right top"]
   },
   "colors": {
     "accentcolor": "blue",
     "textcolor": "#ffffff"
   }
 }

You can also fill the header with a repeating 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": {
     "headerURL": "images/blank.png",
     "additional_backgrounds": [ "images/logo.png"]
   },
   "properties": {
     "additional_backgrounds_alignment": [ "top" ],
     "additional_backgrounds_tiling": [ "repeat"  ]
   },
   "colors": {
     "accentcolor": "green",
     "textcolor": "#000"
   }
 }

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

  "theme": {
    "images": {
      "headerURL": "weta.png"
    },
      
    "colors": {
       "accentcolor": "darkgreen",
       "textcolor": "white",
       "toolbar": "blue",
       "toolbar_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 something like this:

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

Browser compatibility

ChromeEdgeFirefoxFirefox for AndroidOpera
Basic support Yes No55 No No
colors.accentcolor No No551 No No
colors.background_tab_text Yes2 No59 No No
colors.bookmark_text Yes2 No581 No No
colors.frame Yes2 No553 No No
colors.frame_inactive Yes2 No60 No No
colors.frame_incognito Yes2 No No No No
colors.frame_incognito_inactive Yes2 No No No No
colors.icons No No60 No No
colors.icons_attention No No60 No No
colors.ntp_background Yes2 No No No No
colors.ntp_header Yes2 No No No No
colors.ntp_link Yes2 No No No No
colors.ntp_text Yes2 No No No No
colors.tab_text Yes2 No553 No No
colors.textcolor No No551 No No
colors.toolbar Yes2 No571 No No
colors.toolbar_bottom_separator No No581 No No
colors.toolbar_field No No571 No No
colors.toolbar_field_border No No59 No No
colors.toolbar_field_text No No571 No No
colors.toolbar_text No No571 No No
colors.toolbar_top_separator No No581 No No
colors.toolbar_vertical_separator No No581 No No

1. Before version 59, the RGB array form was not supported for this property.

2. The CSS color form is not supported for this property.

3. Before version 59, the CSS color form was not supported for this property.

Chrome compatibility

Firefox property Chrome property
images/headerURL

images/theme_frame

In Chrome, the image is anchored to the top left of the header and tiled if it doesn’t fill the header area.

images/additional_backgrounds Not supported
colors/accentcolor colors/frame
colors/textcolor Incorrectly implemented as colors/tab_text from Firefox 55 to 58, fixed as colors/background_tab_text from Firefox 59 onward
colors/toolbar_text colors/bookmark_text
properties/additional_backgrounds_alignment Not supported
properties/additional_backgrounds_tiling Not supported

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

"theme": {
  "colors": {
     "frame": [255, 0, 0],
     "background_tab_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_text required the array form, while other properties required the CSS color form.

Document Tags and Contributors

Tags: 
 Contributors to this page: wbamberg, ntim, anibyl, hellosct1, juliyvchirkov, rebloor
 Last updated by: wbamberg,