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

Optional as of Firefox 60. Mandatory before Firefox 60.

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 "right 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

Fully optional from Firefox 60 onwards. One of theme_frame or headerURL had to be specified before Firefox 60. Note also that in Firefox 60 onwards, any text-shadow applied to the header text is removed if no headerURL is specified (see bug 1404688).

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

theme_frame String

Fully optional from Firefox 60 onwards. One of theme_frame or headerURL had to be specified before Firefox 60.

Alias for headerURL, provided for Chrome compatibility.

additional_backgrounds Array of String

The additional_backgrounds tag is experimental. It is currently accepted in release versions of Firefox, but its behavior is subject to change.

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 (but note that "accentcolor" and "textcolor" were mandatory in Firefox before version 63).

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".

See example
"theme": {
  "colors": {
     "accentcolor": "red",
     "textcolor": "white"
  }
}

button_background_active

The color of the background of the pressed toolbar buttons.

See example
"theme": {
  "colors": {
     "accentcolor": "black",
     "textcolor": "white",
     "button_background_active": "red"
  }
}

button_background_hover

The color of the background of the toolbar buttons on hover.

See example
"theme": {
  "colors": {
     "accentcolor": "black",
     "textcolor": "white",
     "button_background_hover": "red"
  }
}

icons

The color of toolbar icons.

See example
"theme": {
  "colors": {
     "accentcolor": "black",
     "textcolor": "white",
     "icons": "red"
  }
}

icons_attention

The color of toolbar icons in attention state such as the starred bookmark icon or finished download icon.

See example
"theme": {
  "colors": {
     "accentcolor": "black",
     "textcolor": "white",
     "icons_attention": "red"
  }
}

ntp_background

The new tab page background color.

See example
"theme": {
  "colors": {
     "ntp_background": "red",
     "ntp_text": "white"
  }
}

ntp_text

The new tab page text color.

See example
"theme": {
  "colors": {
     "ntp_background": "red",
     "ntp_text": "white" 
  }
}

popup

The background color of popups (such as the url bar dropdown and the arrow panels).

See example
"theme": {
  "colors": {
     "accentcolor": "black",
     "textcolor": "white",
     "popup": "red"
  }
}

popup_border

The border color of popups.

See example
"theme": {
  "colors": {
     "accentcolor": "black",
     "textcolor": "white",
     "popup": "black",
     "popup_text": "white",
     "popup_border": "red"
  }
}

popup_highlight

The background color of items highlighted using the keyboard inside popups (such as the selected url bar dropdown item).

See example
"theme": {
  "colors": {
     "accentcolor": "black",
     "textcolor": "white",
     "popup_highlight": "red"
  }
}

popup_highlight_text

The text color of items highlighted using the keyboard inside popups.

See example
"theme": {
  "colors": {
     "accentcolor": "black",
     "textcolor": "white",
     "popup_highlight": "black",
     "popup_highlight_text": "red"
  }
}

popup_text

The text color of popups.

See example
"theme": {
  "colors": {
     "accentcolor": "black",
     "textcolor": "white",
     "popup": "black",
     "popup_text": "red"
  }
}

sidebar

The background color of built-in sidebars

See example
"theme": {
  "colors": {
     "sidebar": "red",
     "sidebar_highlight": "white",
     "sidebar_highlight_text": "green",
     "sidebar_text": "white"
  }
}

sidebar_border

The border and splitter color of the browser sidebar

See example
"theme": {
  "colors": {
     "sidebar_border": "red"
  }
}

sidebar_highlight

The background color of highlighted rows in built-in sidebars

See example
"theme": {
  "colors": {
     "sidebar": "red",
     "sidebar_highlight": "white",
     "sidebar_highlight_text": "green",
     "sidebar_text": "white"
  }
}

sidebar_highlight_text

The text color of highlighted rows in built-in sidebars

See example
"theme": {
  "colors": {
    "sidebar": "red",
    "sidebar_highlight": "white",
    "sidebar_highlight_text": "green",
    "sidebar_text": "white"
  }
}

sidebar_text

The text color of built-in sidebars

See example
"theme": {
  "colors": {
     "sidebar": "red",
     "sidebar_highlight": "white",
     "sidebar_highlight_text": "green",
     "sidebar_text": "white"
  }
}

tab_background_separator

The color of the vertical separator of the background tabs.

See example
"theme": {
  "colors": {
     "accentcolor": "black",
     "textcolor": "white",
     "tab_background_separator": "red"
  }
}

A closeup of browser tabs to highlight the separator.

tab_line

The color of the selected tab line.

See example
"theme": {
  "colors": {
     "accentcolor": "black",
     "textcolor": "white",
     "tab_line": "red"
  }
}

tab_loading

The color of the tab loading indicator and the tab loading burst.

See example
"theme": {
  "colors": {
     "accentcolor": "black",
     "textcolor": "white",
     "tab_loading": "red"
  }
}
tab_selected

The background color of the selected tab.

See example
"theme": {
  "images": {
  "headerURL": "weta.png"
},
  "colors": {
     "accentcolor": "black",
     "textcolor": "white",
     "tab_selected": "red"
  }
}

tab_text

From Firefox 59, it represents the text color for the selected tab.

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

See example
"theme": {
  "images": {
  "headerURL": "weta.png"
},
  "colors": {
     "accentcolor": "black",
     "textcolor": "white",
     "tab_selected": "white",
     "tab_text": "red"
  }
}

textcolor

The color of the text displayed in the header area.

See example
"theme": {
  "colors": {
    "accentcolor": "black",
    "toolbar": "white",
    "textcolor": "red"
  }
}

toolbar

The background color for the navigation bar, the bookmarks bar, and the selected tab.

This also sets the background color of the "Find" bar.

See example
"theme": {
  "colors": {
    "accentcolor": "black",
    "toolbar": "red",
    "textcolor": "white"
  }
}

toolbar_bottom_separator

The color of the line separating the bottom of the toolbar from the region below.

See example
"theme": {
  "colors": {
    "accentcolor": "black",
    "textcolor": "white",
    "toolbar_bottom_separator": "red"
  }
}

toolbar_field

The background color for fields in the toolbar, such as the URL bar.

This also sets the background color of the "Find" field.

See example
"theme": {
  "colors": {
    "accentcolor": "black",
    "textcolor": "white",
    "toolbar_field": "red"
  }
}

toolbar_field_border

The border color for fields in the toolbar.

This also sets the border color of the "Find" field.

See example
"theme": {
  "colors": {
    "accentcolor": "black",
    "toolbar": "black",
    "textcolor": "white",
    "toolbar_field": "black",
    "toolbar_field_text": "white",
    "toolbar_field_border": "red"
  }
}

toolbar_field_border_focus

The focused border color for fields in the toolbar.

See example
"theme": {
  "colors": {
    "accentcolor": "black",
    "toolbar": "black",
    "textcolor": "white",
    "toolbar_field": "black",
    "toolbar_field_text": "white",
    "toolbar_field_border_focus": "red"
  }
}

toolbar_field_focus

The focused background color for fields in the toolbar, such as the URL bar.

See example
"theme": {
  "colors": {
    "accentcolor": "black",
    "toolbar": "black",
    "textcolor": "white",
    "toolbar_field": "black",
    "toolbar_field_text": "white",
    "toolbar_field_focus": "red"
  }
}

toolbar_field_separator

The color of separators inside the URL bar. In Firefox 58 this was implemented as toolbar_vertical_separator.

See example
"theme": {
  "colors": {
    "accentcolor": "black",
    "toolbar": "black",
    "textcolor": "white",
    "toolbar_field_separator": "red"
  }
}

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

toolbar_field_text

The color of text in fields in the toolbar, such as the URL bar.

This also sets the color of text in the "Find" field.

See example
"theme": {
  "colors": {
    "accentcolor": "black",
    "toolbar": "black",
    "textcolor": "white",
    "toolbar_field": "black",
    "toolbar_field_text": "red"
  }
}

toolbar_field_text_focus

The color of text in focused fields in the toolbar, such as the URL bar.

See example
"theme": {
  "colors": {
    "accentcolor": "black",
    "toolbar": "black",
    "textcolor": "white",
    "toolbar_field": "black",
    "toolbar_field_text": "white",
    "toolbar_field_text_focus": "red"
  }
}

toolbar_text

The color of toolbar text.

This also sets the color of  text in the "Find" bar.

See example
"theme": {
  "colors": {
    "accentcolor": "black",
    "textcolor": "white",
    "toolbar": "black",
    "toolbar_text": "red"
  }
}

toolbar_top_separator

The color of the line separating the top of the toolbar from the region above.

See example
"theme": {
  "colors": {
    "accentcolor": "black",
    "textcolor": "white",
    "toolbar": "black",
    "toolbar_top_separator": "red"
  }
}

toolbar_vertical_separator

The color of the separator next to the application menu icon. In Firefox 58, it corresponds to the color of separators inside the URL bar.

See example
"theme": {
  "colors": {
    "accentcolor": "black",
    "textcolor": "white",
    "toolbar": "black",
    "toolbar_vertical_separator": "red"
  }
}

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.

Name Alias for
bookmark_text toolbar_text
frame accentcolor
frame_inactive accentcolor
tab_background_text textcolor

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
images Yes No551 No No
colors Yes No55 No No
properties Yes No55 No No

1. Mandatory before Firefox 60

Colors

ChromeEdgeFirefoxFirefox for AndroidOpera
Basic support Yes No55 No No
accentcolor No No551 2 No No
bookmark_text Yes3 No581 No No
button_background_active No No60 No No
button_background_hover No No60 No No
frame Yes3 No554 No No
frame_inactive Yes3 No60 No No
frame_incognito Yes3 No No No No
frame_incognito_inactive Yes3 No No No No
icons No No60 No No
icons_attention No No60 No No
ntp_background Yes3 No No No No
ntp_header Yes3 No No No No
ntp_link Yes3 No No No No
ntp_text Yes3 No No No No
popup No No60 No No
popup_highlight No No61 No No
popup_highlight_text No No61 No No
popup_text No No60 No No
tab_background_separator No No62 No No
tab_background_text Yes3 No59 No No
tab_line No No60 No No
tab_loading No No60 No No
tab_selected No No60 No No
tab_text Yes3 No554 No No
textcolor No No551 2 No No
toolbar Yes3 No571 5 No No
toolbar_bottom_separator No No581 No No
toolbar_field No No571 6 No No
toolbar_field_border No No597 No No
toolbar_field_border_focus No No61 No No
toolbar_field_focus No No61 No No
toolbar_field_separator No No

59

58 — 591 8

No No
toolbar_field_text No No571 9 No No
toolbar_field_text_focus No No61 No No
toolbar_text No No571 10 No No
toolbar_top_separator No No581 No No
toolbar_vertical_separator No No5811 No No

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

2. Before version 63, this property was mandatory.

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

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

5. Before version 61, this did not set the "Find" bar's color.

6. Before version 61, this did not set the "Find" field's background color.

7. Before version 61, this did not set the "Find" field's border color.

8. Supported as toolbar_vertical_separator.

9. Before version 61, this did not set the "Find" field's text color.

10. Before version 61, this did not set the "Find" bar's text color.

11. Before version 59, this had the same meaning as toolbar_field_separator.

Images

ChromeEdgeFirefoxFirefox for AndroidOpera
Basic support Yes No551 No No
headerURL Yes2 No

55

552

No No
additional_backgrounds No No55 No No

1. Mandatory before Firefox 60

2. Supported as theme_frame.

Properties

ChromeEdgeFirefoxFirefox for AndroidOpera
Basic support Yes No55 No No

 

 

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/tab_background_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],
     "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_text required the array form, while other properties required the CSS color form.

Document Tags and Contributors

Tags: 
Last updated by: ntim,