From 198600eb90c2a2073260d4678b7548a3e8acf6ba Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Tue, 23 Jun 2026 05:52:54 +1200 Subject: [PATCH 1/4] Bug 2036647 Add use of CSS gradients to extension themes --- .../manifest.json/theme/index.md | 85 ++++++++++++++++--- .../mozilla/firefox/releases/153/index.md | 1 + 2 files changed, 75 insertions(+), 11 deletions(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md index ae5ee8ade4fcd05..329b5aba959386d 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md @@ -150,27 +150,46 @@ Images should be 200 pixels high to ensure they always fill the header space ver additional_backgrounds - Array of String + Array of String or Object

Warning: The - additional_backgrounds property is experimental. It is - currently accepted in release versions of Firefox, but its behavior - is subject to change. It is not supported in Firefox for Android. + additional_backgrounds property is experimental. It's + accepted in release versions of Firefox, but its behavior + is subject to change. It's not supported in Firefox for Android.

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

Optional.

- 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":. + Each array item is either a URL string for a background image, or a + CSS gradient represented as an object in the form + { "GRADIENT_TYPE": "GRADIENT_PARAMS" }, where: +

+ +

CSS gradient objects are supported from Firefox 153.

+

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

@@ -1325,6 +1344,25 @@ Additionally, this key accepts various properties that are aliases for one of th

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 not specified, defaults to "auto".

+ + color_scheme @@ -1450,6 +1488,31 @@ It will give you a browser that looks 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. +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 -18.096%, #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 {{Compat}} diff --git a/files/en-us/mozilla/firefox/releases/153/index.md b/files/en-us/mozilla/firefox/releases/153/index.md index bb1c37f0b5d5803..fe3763d296b0dc8 100644 --- a/files/en-us/mozilla/firefox/releases/153/index.md +++ b/files/en-us/mozilla/firefox/releases/153/index.md @@ -76,6 +76,7 @@ Firefox 153 is the current [Beta version of Firefox](https://www.firefox.com/en- - Supports the {{WebExtAPIRef("userScripts.execute()")}} method, enabling extensions to inject user scripts on demand into a tab or frame. Unlike {{WebExtAPIRef("userScripts.register()")}}, this method supports one-off injection of multiple script sources executed in a defined order. ([Firefox bug 1930776](https://bugzil.la/1930776)) - Adds the {{WebExtAPIRef("publicSuffix")}} API, enabling extensions to determine the registrable domain (eTLD+1) and public suffix of a hostname using the browser's built-in [Public Suffix List](https://publicsuffix.org/). The API provides three synchronous methods: {{WebExtAPIRef("publicSuffix.isKnownSuffix()")}}, {{WebExtAPIRef("publicSuffix.getKnownSuffix()")}}, and {{WebExtAPIRef("publicSuffix.getDomain()")}}. ([Firefox bug 1315558](https://bugzil.la/1315558)) - Extension content scripts can now read and modify constructed stylesheets in {{domxref("document.adoptedStyleSheets")}} and {{domxref("ShadowRoot.adoptedStyleSheets")}}, without `.wrappedJSObject`. ([Firefox bug 1751346](https://bugzil.la/1751346)) +- The [`theme`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/theme) manifest key's `images.additional_backgrounds` property now supports CSS gradients in addition to image URLs. A new `properties.additional_backgrounds_size` property controls the size of each additional background item. ([Firefox bug 2036647](https://bugzil.la/2036647)) - For contextual identities (containers): - Adds the {{WebExtAPIRef("contextualIdentities.getSupportedColors()")}} and {{WebExtAPIRef("contextualIdentities.getSupportedIcons()")}} methods to retrieve the supported colors and icons, avoiding the need to hardcode those values. ([Firefox bug 2044712](https://bugzil.la/2044712)) - Updates the colors available. `"turquoise"` is renamed to `"cyan"`, `"toolbar"` is renamed to `"gray"`, and `"violet"` is added. The legacy names `"turquoise"` and `"toolbar"` are accepted for backward compatibility. To avoid hardcoding color names, use {{WebExtAPIRef("contextualIdentities.getSupportedColors()")}} to retrieve the available colors. ([Firefox bug 2044354](https://bugzil.la/2044354)) From 3a42ece409bbe57375faf6b4011e619cb4b2819e Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Tue, 23 Jun 2026 06:40:27 +1200 Subject: [PATCH 2/4] Update redirect link --- .../mozilla/add-ons/webextensions/manifest.json/theme/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md index 329b5aba959386d..48dfb45408f34da 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md @@ -1355,7 +1355,7 @@ Additionally, this key accepts various properties that are aliases for one of th An array of values defining the size of the corresponding "additional_backgrounds": array item. Accepts the same values as the CSS - background-size + background-size property, such as "auto", "cover", "contain", or explicit width and height values (for example, "100px 200px"). From b419067252e86222ba4ad2b5733b5e30fa8a51dd Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Wed, 24 Jun 2026 04:37:09 +1200 Subject: [PATCH 3/4] Added theme_frame support details --- .../manifest.json/theme/index.md | 48 +++++++++---------- 1 file changed, 22 insertions(+), 26 deletions(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md index 48dfb45408f34da..9318c5087639e9c 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md @@ -130,11 +130,12 @@ Images should be 200 pixels high to ensure they always fill the header space ver theme_frame - String + String or Object

- The URL of a foreground image to be added to the header area and - anchored to the upper right corner of the header area. + A foreground image 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.

@@ -161,31 +162,13 @@ Images should be 200 pixels high to ensure they always fill the header space ver

- An array of additional background items to be added to the header area - and displayed behind the "theme_frame": image. These items - layer the first item in the array on top and the last item at the bottom. + An array of additional background items, image URLs or CSS gradient, to be added to + the header area and displayed behind the + "theme_frame": image. These 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.

-

- Each array item is either a URL string for a background image, or a - CSS gradient represented 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, or - repeating-conic-gradient. -
    • -
  • - GRADIENT_PARAMS contains the parameters for that CSS - gradient function, as described in - CSS gradient values. -
    • -
-

CSS gradient objects are supported from Firefox 153.

By default, all items are anchored to the upper right corner of the header area, but their alignment, repeat, and size behavior can be @@ -196,6 +179,19 @@ Images should be 200 pixels high to ensure they always fill the header space ver +### 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](/en-US/docs/Web/CSS/Reference/Values/gradient). + ### 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: From 330f60bf07965bf7506dd9c4141559232e5f3b1e Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Fri, 3 Jul 2026 07:02:30 +1200 Subject: [PATCH 4/4] Updates for feedback --- .../manifest.json/theme/index.md | 36 +++++++------------ 1 file changed, 13 insertions(+), 23 deletions(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md b/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md index 9318c5087639e9c..728063e4ffb283a 100644 --- a/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md @@ -47,9 +47,6 @@ Use the `theme` key to define a static theme to apply to Firefox. When provided > [!NOTE] > Since May 2019, themes need to be signed to be installed ([Firefox bug 1545109](https://bugzil.la/1545109)). See [Signing and distributing your add-on](https://extensionworkshop.com/documentation/publish/signing-and-distribution-overview/#distributing-your-addon) for more details. -> [!NOTE] -> A new version of Firefox for Android, based on GeckoView, is under development. A [pre-release version](https://play.google.com/store/apps/details?id=org.mozilla.fenix) is available. The pre-release version does not support themes. - ## Image formats The following image formats are supported in all theme image properties: @@ -90,7 +87,7 @@ The theme key is an object that takes the following properties: colors Object -

Mandatory.

+

Mandatory

A JSON object whose properties represent the colors of various parts of the browser. See colors for @@ -105,7 +102,7 @@ The theme key is an object that takes the following properties:

Optional

This object has properties that affect how the - "additional_backgrounds" images are displayed and color schemes are applied. See + "additional_backgrounds" items are displayed and color schemes are applied. See properties for details on the properties that this object can contain.

@@ -133,7 +130,7 @@ Images should be 200 pixels high to ensure they always fill the header space ver String or Object

- A foreground image or CSS gradient + 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.

@@ -145,7 +142,7 @@ Images should be 200 pixels high to ensure they always fill the header space ver

- Optional in desktop Firefox 60 onwards. Required in Firefox for Android. + Optional in desktop Firefox 60 onwards.

@@ -158,17 +155,17 @@ Images should be 200 pixels high to ensure they always fill the header space ver Warning: The additional_backgrounds property is experimental. It's accepted in release versions of Firefox, but its behavior - is subject to change. It's not supported in Firefox for Android. + is subject to change.

- An array of additional background items, image URLs or CSS gradient, to be added to + 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": image. These items layer the first item in + "theme_frame": items. These 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.

+

Optional

By default, all items are anchored to the upper right corner of the header area, but their alignment, repeat, and size behavior can be @@ -218,13 +215,6 @@ All these properties can be specified as either a string containing any valid [C > [!NOTE] > [In Chrome, colors may only be specified as RGB arrays](#chrome_compatibility). -> -> In Firefox for Android colors can be specified using: -> -> - full hexadecimal notation, that is #RRGGBB only. _alpha_ and shortened syntax, as in #RGB\[A], are not supported. -> - [Functional notation](/en-US/docs/Web/CSS/Reference/Values/color_value) (RGB arrays) for themes targeting Firefox 68.2 or later. -> -> Colors for Firefox for Android themes cannot be specified using color names. @@ -378,7 +368,7 @@ All these properties can be specified as either a string containing any valid [C

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

@@ -401,7 +391,7 @@ All these properties can be specified as either a string containing any valid [C

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 images specified in "theme_frame" and + through the items specified in "theme_frame" and "additional_backgrounds".

@@ -1420,7 +1410,7 @@ A basic theme must define an image to add to the header, the accent color to use } ``` -Multiple images 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 image: +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": { @@ -1492,7 +1482,7 @@ This example (Firefox 153+) mixes image backgrounds with a CSS linear gradient: "additional_backgrounds": [ "background-image1.svg", "background-image2.svg", - { "linear-gradient": "to bottom, #FF6BBA -18.096%, #FFC999 50%" } + { "linear-gradient": "to bottom, #FF6BBA -20%, #FFC999 50%" } ] }, "properties": { @@ -1517,7 +1507,7 @@ This results in: In Chrome: -- `colors/toolbar_text` is not used, use `colors/bookmark_text` instead. +- `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: