1. Mozilla
  2. Add-ons
  3. Browser extensions
  4. manifest.json
  5. theme

theme

Type Object
Mandatory No
Manifest version 2 or higher
Example
json
"theme": {
  "images": {
    "theme_frame": "images/sun.jpg"
  },
  "colors": {
    "frame": "#CF723F",
    "tab_background_text": "black"
  }
}

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 is provided, this key provides the theme used when Firefox is using the light color scheme.

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

Note: 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:

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 properties that affect how the "additional_backgrounds" items are displayed and color schemes are applied. See properties for details on the properties that this object can contain.

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
theme_frame String or Object

A foreground image (defined by the path to an image asset packaged in the extension) or CSS gradient to be added to the header area and anchored to the upper right corner of the header area. CSS gradients are supported from Firefox 153.

Note: Chrome anchors the image to the top left of the header and if the image doesn't fill the header area tile the image.

Optional in desktop Firefox 60 onwards.

additional_backgrounds Array of String or Object

Warning: The additional_backgrounds property is experimental. It's accepted in release versions of Firefox, but its behavior is subject to change.

An array of additional background items, each being either the path to an image asset packaged in the extension or CSS gradient, to be added to the header area and displayed behind the "theme_frame": item. These additional background items layer the first item in the array on top and the last item at the bottom. CSS gradients are supported from Firefox 153.

Optional

By default, all items are anchored to the upper right corner of the header area, but their alignment, repeat, and size behavior, and the area of the browser window they are drawn in, can be controlled by "properties":.

As additional background items display behind the theme_frame item, if theme_frame is set as a CSS gradient, any additional background items are hidden.

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.

Note: Color properties introduced in Firefox 157 (Nova) are ignored in earlier Firefox versions; use strict_min_version for themes designed only for Nova.

How these properties affect the Firefox UI is shown here:

Firefox 157 and later (Nova): Overview of the color properties and how they apply to Firefox UI components in Nova

Firefox 156 and earlier: Overview of the color properties and how they apply to Firefox UI components

Note: 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 ].

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

Name Description
bookmark_text

The color of text and icons in the bookmark and find bars. Also, if tab_text isn't defined it sets the color of the active tab text and if icons isn't defined the color of the toolbar icons. Provided as Chrome compatible alias for toolbar_text.

Note: Ensure any color used contrasts well with those used in frame and frame_inactive or toolbar if you're using that property.

Where icons isn't defined, also ensure good contrast with button_background_active and button_background_hover.

See example
json
"theme": {
  "colors": {
    "frame": "black",
    "tab_background_text": "white",
    "tab_text": "white",
    "toolbar": "black",
    "bookmark_text": "red"
  }
}

Firefox 157 and later (Nova): Browser Firefox is black. Browser's tab is black with white text. URL bar and the find in page bar are white with black text but all the browser and the find in page bar icons are red.

Firefox 156 and earlier: Browser Firefox is black. Browser's tab is black with white text. URL bar and the find in page bar are white with black text but all the browser and the find in page bar icons are red.

button_background_active

The color of the background of the pressed toolbar buttons.

See example
json
"theme": {
  "colors": {
     "frame": "black",
     "tab_background_text": "white",
     "button_background_active": "red"
  }
}

Firefox 157 and later (Nova): Browser firefox is black. Browser's tabs and URL bar are gray with white text. The customize toolbar icon in the url bar in white with a red background is pressed and a popup is open displaying a short list of thing to add to the toolbar such as the browser's library and the sidebars.

Firefox 156 and earlier: Browser firefox is black. Browser's tabs and URL bar are gray with white text. The customize toolbar icon in the url bar in white with a red background is pressed and a popup is open displaying a short list of thing to add to the toolbar such as the browser's library and the sidebars.

button_background_hover

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

See example
json
"theme": {
  "colors": {
     "frame": "black",
     "tab_background_text": "white",
     "button_background_hover": "red"
  }
}

Firefox 157 and later (Nova): Browser firefox is black. Browser's tabs and URL bar are gray with white text. The go back one page icon is white with a red circle background.

Firefox 156 and earlier: Browser firefox is black. Browser's tabs and URL bar are gray with white text. The go back one page icon is white with a red circle background.

icons

The color of toolbar icons, excluding those in the find toolbar.

Note: Ensure the color used contrasts well with those used in frame, frame_inactive, button_background_active, and button_background_hover.

See example
json
"theme": {
  "colors": {
     "frame": "black",
     "tab_background_text": "white",
     "icons": "red"
  }
}

Firefox 157 and later (Nova): Browser firefox is black. Browser's tabs and URL bar are gray with white text. The URL bar and open a new tab icons are red. The red icons contrast well with the black background color of the header area.

Firefox 156 and earlier: Browser firefox is black. Browser's tabs and URL bar are gray with white text. The URL bar and open a new tab icons are red. The red icons contrast well with the black background color of the header area.

icons_attention

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

Note: Ensure the color used contrasts well with those used in frame, frame_inactive, button_background_active, and button_background_hover.

See example
json
"theme": {
  "colors": {
     "frame": "black",
     "tab_background_text": "white",
     "icons_attention": "red"
  }
}

Firefox 157 and later (Nova): Browser firefox is black. Browser's tabs and URL bar are gray with white text. The bookmark this page icon is red and pressed, an open popup name edit this bookmark is displayed. While in attention state, the toolbar icons contrast well with the black background of the header area.

Firefox 156 and earlier: Browser firefox is black. Browser's tabs and URL bar are gray with white text. The bookmark this page icon is red and pressed, an open popup name edit this bookmark is displayed. While in attention state, the toolbar icons contrast well with the black background of the header area.

frame

The color of the header area background, displayed in the part of the header not covered or visible through the items specified in "theme_frame" and "additional_backgrounds".

See example
json
"theme": {
  "colors": {
     "frame": "red",
     "tab_background_text": "white"
  }
}

Firefox 157 and later (Nova): Browser firefox is red with white text. Browsers tabs are lighter red, also with white text. URL bar is very light red with black text

Firefox 156 and earlier: Browser firefox is red with white text. Browsers tabs are lighter red, also with white text. URL bar is very light red with black text

frame_inactive

The color of the header area background when the browser window is inactive, displayed in the part of the header not covered or visible through the items specified in "theme_frame" and "additional_backgrounds".

See example
json
"theme": {
  "colors": {
     "frame": "red",
     "frame_inactive": "gray",
     "tab_text": "white"
  }
}

Firefox 157 and later (Nova): Browser firefox is gray. Browser's tabs and URL bar are lighter gray. The tab text is white and the URL bar icon are darker gray.

Firefox 156 and earlier: Browser firefox is gray. Browser's tabs and URL bar are lighter gray. The tab text is white and the URL bar icon are darker gray.

ntp_background

The new tab page background color.

See example
json
"theme": {
  "colors": {
     "ntp_background": "red"
  }
}

Firefox 157 and later (Nova): Firefox showing a new tab page. The background of the page is red.

Firefox 156 and earlier: Firefox showing a new tab page. The background of the page is red.

ntp_card_background

The new tab page card background color.

See example
json
"theme": {
  "colors": {
     "ntp_card_background": "red"
  }
}

Firefox 157 and later (Nova): Firefox showing a new tab page. On the page, the background to the search bar and shortcut buttons is red.

Firefox 156 and earlier: Firefox showing a new tab page. On the page, the background to the search bar and shortcut buttons is red.

ntp_text

The new tab page text color.

Note: Ensure the color used contrasts well with that used in ntp_background and ntp_card_background.

Note: In Nova, the text in the search box is not styled. It takes the default text color.

See example
json
"theme": {
  "colors": {
     "ntp_text": "red"
  }
}

Firefox 157 and later (Nova): Firefox showing a new tab page. On the page, the text is in red.

Firefox 156 and earlier: Firefox showing a new tab page. On the page, the text is in red.

popup

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

Note: In Firefox 157 and later (Nova), the URL bar dropdown doesn't use popup or popup_text: it keeps the browser's default colors.

See example
json
"theme": {
  "colors": {
     "frame": "black",
     "tab_background_text": "white",
     "popup": "red"
  }
}

Firefox 157 and later (Nova): Browser firefox is black. Browser's tabs and URL bar are lighter gray with icons and text in white. The bookmark this page icon is blue and pressed, an open popup name 'edit this bookmark' is displayed with a red background. The background color of the popup is red.

Firefox 156 and earlier: Browser firefox is black. Browser's tabs and URL bar are lighter gray with icons and text in white. The bookmark this page icon is blue and pressed, an open popup name 'edit this bookmark' is displayed with a red background. The background color of the popup is red.

popup_border

The border color of popups.

See example
json
"theme": {
  "colors": {
     "frame": "black",
     "tab_background_text": "white",
     "popup": "black",
     "popup_text": "white",
     "popup_border": "red"
  }
}

Firefox 157 and later (Nova): Browser firefox is black. Browser's tabs and URL bar are lighter gray with icons and text in white. The bookmark this page icon is blue and pressed, an open popup name 'edit this bookmark' is displayed with a red outline and black background. The popup's border is red.

Firefox 156 and earlier: Browser firefox is black. Browser's tabs and URL bar are lighter gray with icons and text in white. The bookmark this page icon is blue and pressed, an open popup name 'edit this bookmark' is displayed with a red outline and black background. The popup's border is red.

popup_highlight

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

Note: It's recommended to define popup_highlight_text to override the browser default text color on various platforms.

See example
json
"theme": {
  "colors": {
     "frame": "black",
     "tab_background_text": "white",
     "popup_highlight": "red",
     "popup_highlight_text": "white"
  }
}

Firefox 157 and later (Nova): screenshot of firefox is black. Browser's tabs and URL bar are lighter gray with icons and text in white. A search results popup is displayed with a highlighted item's background in red. The background color of the highlighted item inside the popup is red.

Firefox 156 and earlier: screenshot of firefox is black. Browser's tabs and URL bar are lighter gray with icons and text in white. A search results popup is displayed with a highlighted item's background in red. The background color of the highlighted item inside the popup is red.

popup_highlight_text

The text color of items highlighted inside popups.

Note: Ensure the color used contrasts well with that used in popup_highlight.

See example
json
"theme": {
  "colors": {
     "frame": "black",
     "tab_background_text": "white",
     "popup_highlight": "black",
     "popup_highlight_text": "red"
  }
}

Firefox 157 and later (Nova): Browser firefox is black. Browser's tabs and URL bar are lighter gray with icons and text in white. A search results popup is displayed with a highlighted item's text in red with a black background. The text color of the highlighted item contrasts well with the black background color of this item.

Firefox 156 and earlier: Browser firefox is black. Browser's tabs and URL bar are lighter gray with icons and text in white. A search results popup is displayed with a highlighted item's text in red with a black background. The text color of the highlighted item contrasts well with the black background color of this item.

popup_text

The text color of popups.

Note: Ensure the color used contrasts well with that used in popup.

Note: In Firefox 157 and later (Nova), the URL bar dropdown doesn't use popup or popup_text: it keeps the browser's default colors.

See example
json
"theme": {
  "colors": {
     "frame": "black",
     "tab_background_text": "white",
     "popup": "black",
     "popup_text": "red"
  }
}

Firefox 157 and later (Nova): Firefox with a black frame and white tab text. The Add bookmark panel is open, with a black background and its labels, fields, and buttons in red.

Firefox 156 and earlier: Browser firefox is black. Browser's tabs and URL bar are lighter gray with icons and text in white. A search results popup is displayed with items texts in red. The text color contrasts well with the black background color of the popup.

sidebar

The background color of the sidebar.

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

Firefox 157 and later (Nova): A close-up screenshot of a browser windows's open sidebar. The background color of the sidebar is red.

Firefox 156 and earlier: A close-up screenshot of a browser windows's open sidebar. The background color of the sidebar is red.

sidebar_border

The border and splitter color of the browser sidebar

Note: In Firefox 157 and later (Nova), the redesigned sidebar no longer includes a splitter.

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

Firefox 157 and later (Nova): A closeup of the firefox browser bookmarks sidebar with a red horizontal separator between the sidebar title and the sidebar menu. The border and splitter color of the sidebar is red.

Firefox 156 and earlier: A closeup of the firefox browser bookmarks sidebar with a red horizontal separator between the sidebar title and the sidebar menu. The border and splitter color of the sidebar is red.

sidebar_highlight

The background color of highlighted rows in built-in sidebars

Note: In Firefox 157 and later (Nova), a highlighted row in the redesigned sidebar keeps the browser's default highlight color, so this property has no visible effect.

See example
json
"theme": {
  "colors": {
     "sidebar_highlight": "red",
     "sidebar_highlight_text": "white"
  }
}

Firefox 157 and later (Nova): The bookmarks sidebar with a row highlighted. The highlighted row keeps the browser's default lavender background rather than the red set by the theme.

Firefox 156 and earlier: A closeup of the firefox browser bookmarks sidebar with a highlighted item. The background color of a highlighted row in the sidebar is red with white text.

sidebar_highlight_text

The text color of highlighted rows in sidebars.

Note: Ensure the color used contrasts well with that used in sidebar_highlight.

Note: In Firefox 157 and later (Nova), a highlighted row in the redesigned sidebar keeps the browser's default text color, so this property has no visible effect.

See example
json
"theme": {
  "colors": {
    "sidebar_highlight": "pink",
    "sidebar_highlight_text": "red",
  }
}

Firefox 157 and later (Nova): The bookmarks sidebar with a row highlighted. The highlighted row's label keeps the browser's default color rather than the red set by the theme.

Firefox 156 and earlier: A closeup of the firefox browser bookmarks sidebar with a highlighted item. The color of the text of a highlighted row in the sidebar is red. The text color contrasts well with the pink background color of the highlighted row.

sidebar_text

The text color of sidebars.

Note: Ensure the color used contrasts well with that used in sidebar.

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

Firefox 157 and later (Nova): A close-up screenshot of a browser windows's open sidebar. The color of the text inside the sidebar is white. The text color contrasts well with the red background of the sidebar.

Firefox 156 and earlier: A close-up screenshot of a browser windows's open sidebar. The color of the text inside the sidebar is white. The text color contrasts well with the red background of the sidebar.

tab_background_separator

Warning: tab_background_separator is not supported starting with Firefox 89.

The color of the vertical separator of the background tabs.

See example
json
"theme": {
  "colors": {
     "frame": "black",
     "tab_background_text": "white",
     "tab_background_separator": "red"
  }
}

Firefox 157 and later (Nova): A closeup of browser tabs to highlight the separator.

Firefox 156 and earlier: A closeup of browser tabs to highlight the separator.

tab_background_text

The color of the text displayed in the inactive page tabs. If tab_text or bookmark_text isn't specified, applies to the active tab text.

Note: Ensure the color used contrasts well with those used in tab_selected or frame and frame_inactive.

See example
json
"theme": {
  "colors": {
    "frame": "black",
    "toolbar": "white",
    "tab_background_text": "red"
  }
}

Firefox 157 and later (Nova): A screenshot of a browser window with one open tab. Browser is black. Browser's tabs and URL bar are white with red icons and red text. The color of the text in the open tab is red. The text color contrasts well with the black background color of the tab.

Firefox 156 and earlier: A screenshot of a browser window with one open tab. Browser is black. Browser's tabs and URL bar are white with red icons and red text. The color of the text in the open tab is red. The text color contrasts well with the black background color of the tab.

tab_line

The color of the selected tab line.

See example
json
"theme": {
  "colors": {
     "frame": "black",
     "tab_background_text": "white",
     "tab_line": "red"
  }
}

Firefox 157 and later (Nova): Browser firefox is black. Browser's tabs and URL bar are darker gray with lighter gray icons and white text. The selected tab has a red outline.

Firefox 156 and earlier: Browser firefox is black. Browser's tabs and URL bar are darker gray with lighter gray icons and white text. The selected tab has a red outline.

tab_loading

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

Note: In Firefox 157 and later (Nova), the tab loading indicator keeps its default color, so this property has no visible effect.

See example
json
"theme": {
  "colors": {
     "frame": "black",
     "tab_background_text": "white",
     "tab_loading": "red"
  }
}

Firefox 157 and later (Nova): Firefox with a black frame and white tab text, loading a page. The loading indicator in the tab is the browser's default gray rather than the red set by the theme.

Firefox 156 and earlier: A screenshot of a browser window with one open tab. Browser is black. Browser's tabs and URL bar are darker gray with icons and text in white. Inside the selected tab an animated loading indicator is red.

tab_selected

The background color of the selected tab. When not in use selected tab color is set by frame and the frame_inactive.

Note: Nova removed the selected tab drop shadow. To ensure selected tabs are clearly visible, set this property to a color that contrasts with frame and frame_inactive.

See example
json
"theme": {
  "images": {
  "theme_frame": "weta.png"
},
  "colors": {
     "frame": "black",
     "tab_background_text": "white",
     "tab_selected": "red"
  }
}

Firefox 157 and later (Nova): A screenshot of a browser window with one open tab. Browser is black. Browser's tabs and URL bar are darker gray with icons and text in white. The selected tab has red background and white text.

Firefox 156 and earlier: A screenshot of a browser window with one open tab. Browser is black. Browser's tabs and URL bar are darker gray with icons and text in white. The selected tab has red background and white text.

tab_text

From Firefox 59, it represents the text color for the selected tab. If tab_line isn't specified, it also defines the color of the selected tab line.

Note: Ensure the color used contrasts well with those used in tab_selected or frame and frame_inactive.

See example
json
"theme": {
  "images": {
  "theme_frame": "weta.png"
},
  "colors": {
     "frame": "black",
     "tab_background_text": "white",
     "tab_selected": "white",
     "tab_text": "red"
  }
}

Firefox 157 and later (Nova): Browser firefox has a picture of an insect theme. URL bar is lighter gray with white icons. The selected tab text is red with white background.

Firefox 156 and earlier: Browser firefox has a picture of an insect theme. URL bar is lighter gray with white icons. The selected tab text is red with white background.

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
json
"theme": {
  "colors": {
    "frame": "black",
    "toolbar": "red",
    "tab_background_text": "white"
  }
}

Firefox 157 and later (Nova): Browser firefox is black. Browser's tab, find in page bar and URL bar are red with white text and icons, except for the find in page bar where the text and icon are black.

Firefox 156 and earlier: Browser firefox is black. Browser's tab, find in page bar and URL bar are red with white text and icons, except for the find in page bar where the text and icon are black.

toolbar_bottom_separator

The color of the line separating the top and left edges of the area containing the web page. It therefore separates the page content from the toolbar above it and, where the sidebar is displayed, from the sidebar to its left.

See example
json
"theme": {
  "colors": {
    "frame": "black",
    "tab_background_text": "white",
    "toolbar_bottom_separator": "red"
  }
}

Firefox 157 and later (Nova): Browser Firefox is black with white tab text and the sidebar showing its icons. A red line runs along the top and left edges of the area holding the web page, separating that area from the toolbar above it and from the sidebar to its left.

Firefox 156 and earlier: Browser firefox is black. Browser's tab and URL bar are lighter gray with white text and icons. A horizontal red line separates the bottom of the toolbar and the beginning of the display of the web page.

toolbar_field

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

This also sets the background color of the Find in page field.

See example
json
"theme": {
  "colors": {
    "frame": "black",
    "tab_background_text": "white",
    "toolbar_field": "red"
  }
}

Firefox 157 and later (Nova): Browser firefox is black. Browser's tab, find in page bar and URL bar are lighter gray with white text and icons. The background color of the URL bar is red. The find in page bar is white with black text. The find in page field is red with black text.

Firefox 156 and earlier: Browser firefox is black. Browser's tab, find in page bar and URL bar are lighter gray with white text and icons. The background color of the URL bar is red. The find in page bar is white with black text. The find in page field is red with black text.

toolbar_field_border

The border color for fields in the toolbar.

This also sets the border color of the Find in page field.

See example
json
"theme": {
  "colors": {
    "frame": "black",
    "toolbar": "black",
    "tab_background_text": "white",
    "toolbar_field": "black",
    "toolbar_field_text": "white",
    "toolbar_field_border": "red"
  }
}

Firefox 157 and later (Nova): Browser firefox is black. Browser's tab, find in page and URL bar are black with white text and icons. The URL bar and find in page fields are outlined in red.

Firefox 156 and earlier: Browser firefox is black. Browser's tab, find in page and URL bar are black with white text and icons. The URL bar and find in page fields are outlined in red.

toolbar_field_border_focus

The focused border color for fields in the toolbar.

See example
json
"theme": {
  "colors": {
    "frame": "black",
    "toolbar": "black",
    "tab_background_text": "white",
    "toolbar_field": "black",
    "toolbar_field_text": "white",
    "toolbar_field_border_focus": "red"
  }
}

Firefox 157 and later (Nova): Browser firefox is black. Browser's tab and URL bar are black with white text and icons. The url bar field is focused and outlined in red.

Firefox 156 and earlier: Browser firefox is black. Browser's tab and URL bar are black with white text and icons. The url bar field is focused and outlined in red.

toolbar_field_focus

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

See example
json
"theme": {
  "colors": {
    "frame": "black",
    "toolbar": "black",
    "tab_background_text": "white",
    "toolbar_field": "black",
    "toolbar_field_text": "white",
    "toolbar_field_focus": "red"
  }
}

Firefox 157 and later (Nova): Browser firefox is black. Browser's tab, find in page and URL bar are black with white text and icons. The background color of the focused URL bar is red and the text is white.

Firefox 156 and earlier: Browser firefox is black. Browser's tab, find in page and URL bar are black with white text and icons. The background color of the focused URL bar is red and the text is white.

toolbar_field_highlight The background color used to indicate the current selection of text in the URL bar (and the search bar, if it's configured to be separate).
See example
json
"theme": {
  "colors": {
    "toolbar_field": "rgb(255 255 255 / 91%)",
    "toolbar_field_text": "rgb(0 100 0)",
    "toolbar_field_highlight": "rgb(180 240 180 / 90%)",
    "toolbar_field_highlight_text": "rgb(0 80 0)"
  }
}

Firefox 157 and later (Nova): Browser firefox is white. Browser's tab and URL bar are white with text and icons in black. The URL bar field is focused and outlined in blue and URL bar text is selected.

Firefox 156 and earlier: Browser firefox is white. Browser's tab and URL bar are white with text and icons in black. The URL bar field is focused and outlined in blue and URL bar text is selected.

Here, the toolbar_field_highlight field specifies that the highlight color is a light green, while the text is set to a dark-to-medium green using toolbar_field_highlight_text.

toolbar_field_highlight_text

The color used to draw text that's currently selected in the URL bar (and the search bar, if it's configured to be separate box).

Note: Ensure the color used contrasts well with those used in toolbar_field_highlight.

See example
json
"theme": {
  "colors": {
    "toolbar_field": "rgb(255 255 255 / 91%)",
    "toolbar_field_text": "rgb(0 100 0)",
    "toolbar_field_highlight": "rgb(180 240 180 / 90%)",
    "toolbar_field_highlight_text": "rgb(0 80 0)"
  }
}

Firefox 157 and later (Nova): Browser firefox is white. Browser's tab and URL bar are white with text and icons in black. The URL bar field is focused and outlined in blue and URL bar text is selected.

Firefox 156 and earlier: Browser firefox is white. Browser's tab and URL bar are white with text and icons in black. The URL bar field is focused and outlined in blue and URL bar text is selected.

Here, the toolbar_field_highlight_text field is used to set the text color to a dark medium-dark green, while the highlight color is a light green.

toolbar_field_separator

Warning: toolbar_field_separator is not supported starting with Firefox 89.

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

See example
json
"theme": {
  "colors": {
    "frame": "black",
    "toolbar": "black",
    "tab_background_text": "white",
    "toolbar_field_separator": "red"
  }
}

Firefox 157 and later (Nova): A screenshot of a browser window with one open tab. Browser firefox is black. Browser's tab and URL bar are black with text and icons in white. Inside the white URL bar field, after the reader mode icon a red vertical line separating the rest of URL bar icons. The color of the vertical separator line inside the URL bar is red.

Firefox 156 and earlier: A screenshot of a browser window with one open tab. Browser firefox is black. Browser's tab and URL bar are black with text and icons in white. Inside the white URL bar field, after the reader mode icon a red vertical line separating the rest of URL bar icons. The color of the vertical separator line inside the URL bar is red.

In this screenshot, "toolbar_vertical_separator" is the red 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 in page field.

Note: Ensure the color used contrasts well with those used in toolbar_field.

See example
json
"theme": {
  "colors": {
    "frame": "black",
    "toolbar": "black",
    "tab_background_text": "white",
    "toolbar_field": "black",
    "toolbar_field_text": "red"
  }
}

Firefox 157 and later (Nova): A screenshot of a browser window with one open tab. Browser is black. Browser's tab and URL bar are black with white text and icons. The text inside the URL bar is red. The icons and find in page field have red text with black background.

Firefox 156 and earlier: A screenshot of a browser window with one open tab. Browser is black. Browser's tab and URL bar are black with white text and icons. The text inside the URL bar is red. The icons and find in page field have red text with black background.

toolbar_field_text_focus

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

Note: Ensure the color used contrasts well with those used in toolbar_field_focus.

See example
json
"theme": {
  "colors": {
    "frame": "black",
    "toolbar": "black",
    "tab_background_text": "white",
    "toolbar_field": "black",
    "toolbar_field_text": "white",
    "toolbar_field_text_focus": "red"
  }
}

Firefox 157 and later (Nova): A screenshot of a browser window with two open tabs. Browser is black. Browser's tab and URL bar are black with text and icons in white. The URL bar has focus; the bar's text and icons are red with black background.

Firefox 156 and earlier: A screenshot of a browser window with two open tabs. Browser is black. Browser's tab and URL bar are black with text and icons in white. The URL bar has focus; the bar's text and icons are red with black background.

toolbar_text

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

Note: For compatibility with Chrome, use the alias bookmark_text.

See example
json
"theme": {
  "colors": {
    "frame": "black",
    "tab_background_text": "white",
    "toolbar": "black",
    "toolbar_text": "red"
  }
}

Firefox 157 and later (Nova): A screenshot of a browser window with one open tab. Browser is black. Browser's tab, find in page bar, and URL bar are black with red text and icons. The text inside the active tab, the navigator bar and the find bar is red.

Firefox 156 and earlier: A screenshot of a browser window with one open tab. Browser is black. Browser's tab, find in page bar, and URL bar are black with red text and icons. The text inside the active tab, the navigator bar and the find bar is red.

toolbar_top_separator

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

See example
json
"theme": {
  "colors": {
    "frame": "black",
    "tab_background_text": "white",
    "toolbar": "black",
    "toolbar_top_separator": "red"
  }
}

Firefox 157 and later (Nova): A screenshot of a browser window with one open tab. Browser is black. Browser's tab and URL bar are black with white text and icons. A red line separates the top of the URL bar from the browser.

Firefox 156 and earlier: A screenshot of a browser window with one open tab. Browser is black. Browser's tab and URL bar are black with white text and icons. A red line separates the top of the URL bar from the browser.

toolbar_vertical_separator

The color of the separator in the bookmarks toolbar. In Firefox 58, it corresponds to the color of separators inside the URL bar.

See example
json
"theme": {
  "colors": {
    "frame": "black",
    "tab_background_text": "white",
    "toolbar": "black",
    "toolbar_vertical_separator": "red"
  }
}

Firefox 157 and later (Nova): A screenshot of a browser window with one open tab. Browser is black. Browser's tab and URL bar are black with text and icons in white. The color of the vertical line separating the bookmarks toolbar from the content to the right is red.

Firefox 156 and earlier: A screenshot of a browser window with one open tab. Browser is black. Browser's tab and URL bar are black with text and icons in white. The color of the vertical line separating the bookmarks toolbar from the content to the right is 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

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 the array contains fewer items than the additional_backgrounds array, the array is reused for the missing values. For example, if additional_backgrounds contains 5 values and additional_backgrounds_alignment contains ["left", "top"], the third background item is aligned using "left", the fourth using "top", and the fifth "left".

If not specified, defaults to "right 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 the array contains fewer items than the additional_backgrounds array, the array is reused for the missing values. For example, if additional_backgrounds contains 5 values and additional_backgrounds_tiling contains ["no-repeat", "repeat-x"], the third background item is tiled using "no-repeat", the fourth using "repeat-x", and the fifth "no-repeat".

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

Array of String

Optional

An array of values defining the size of the corresponding "additional_backgrounds": array item. Accepts the same values as the CSS background-size property, such as "auto", "cover", "contain", or explicit width and height values (for example, "100px 200px").

If the array contains fewer items than the additional_backgrounds array, the array is reused for the missing values. For example, if additional_backgrounds contains 5 values and additional_backgrounds_size contains ["auto", "100px 100px"], the third background item is sized using "auto", the fourth using "100px 100px", and the fifth "auto".

If not specified, defaults to "auto".
backgrounds_area

String

Optional

Determines the area of the browser window where the theme's background images and gradients are drawn. Options include:

  • "auto" – Firefox chooses the area based on additional_backgrounds_alignment. If any alignment value positions a background at the vertical center or bottom of the header area, the backgrounds are drawn in the top toolbars. Otherwise, they are drawn in the window.
  • "window" – the backgrounds are drawn in the whole browser window, so that they extend behind vertical UI, such as the sidebar and vertical tabs.
  • "top_toolbars" – the backgrounds are drawn only in the horizontal toolbars at the top of the window, that is, the menu bar, tab strip, navigation toolbar, and bookmarks toolbar. Vertical UI, such as the sidebar, uses the frame color instead.

If not specified, defaults to "auto".
color_scheme

String

Optional

Determines which color scheme is applied to the chrome (for example, context menus) and content (for example, built-in pages and the preferred color scheme for web pages). Options include:

  • "auto" – a light or dark scheme based automatically on the theme.
  • "light" – a light scheme.
  • "dark" – a dark scheme.
  • "system" – uses the system scheme.

If not specified, defaults to "auto".
content_color_scheme

String

Optional

Determines which color scheme is applied to the content (for example, built-in pages and preferred color scheme for web pages). Overrides color_scheme. Options include:

  • "auto" – a light or dark scheme based automatically on the theme.
  • "light" – a light scheme.
  • "dark" – a dark scheme.
  • "system" – the system scheme.

If not specified, defaults to "auto".

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:

json
 "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:

json
 "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:

json
 "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:

json
  "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:

Firefox 157 and later (Nova):

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.

Firefox 156 and earlier:

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:

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

This example (Firefox 156+) restricts the background gradient to the horizontal toolbars at the top of the window, so that it doesn't extend behind the sidebar or vertical tabs. Without backgrounds_area, the "right top" alignment causes Firefox to draw the gradient in the whole window:

json
"theme": {
  "images": {
    "additional_backgrounds": [
      { "linear-gradient": "to bottom, rgb(255, 0, 128), rgb(0, 128, 255)" }
    ]
  },
  "colors": {
    "frame": "#000080",
    "tab_background_text": "#ffffff"
  },
  "properties": {
    "additional_backgrounds_alignment": ["right top"],
    "additional_backgrounds_tiling": ["no-repeat"],
    "additional_backgrounds_size": ["100% 100%"],
    "backgrounds_area": "top_toolbars"
  }
}

With backgrounds_area set to "top_toolbars", the sidebar uses the frame color. Changing backgrounds_area to "window" draws the gradient across the whole window instead, including behind the sidebar.

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:

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

Help improve MDN

Learn how to contribute

This page was last modified on by MDN contributors.

View this page on GitHub • Report a problem with this content