Skip to content

Bug 2036647 Add use of CSS gradients to extension themes #44551

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rebloor wants to merge 6 commits into
base: main
Choose a base branch
from
+83 −33
Open

Bug 2036647 Add use of CSS gradients to extension themes #44551

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
198600e
Bug 2036647 Add use of CSS gradients to extension themes
rebloor Jun 22, 2026
3a42ece
Update redirect link
rebloor Jun 22, 2026
b419067
Added theme_frame support details
rebloor Jun 23, 2026
76716b1
Merge branch 'main' into Bug-2036647-CSS-gradients-in-extension-themes
rebloor Jun 29, 2026
e75355c
Merge branch 'Bug-2036647-CSS-gradients-in-extension-themes' of ssh:/…
rebloor Jul 2, 2026
330f60b
Updates for feedback
rebloor Jul 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 81 additions & 32 deletions files/en-us/mozilla/add-ons/webextensions/manifest.json/theme/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -90,7 +87,7 @@ The theme key is an object that takes the following properties:
<td><code>colors</code></td>
<td><code>Object</code></td>
<td>
<p>Mandatory.</p>
<p>Mandatory</p>
<p>
A JSON object whose properties represent the colors of various parts
of the browser. See <code><a href="#colors">colors</a></code> for
Expand All @@ -105,7 +102,7 @@ The theme key is an object that takes the following properties:
<p>Optional</p>
<p>
This object has properties that affect how the
<code>"additional_backgrounds"</code> images are displayed and color schemes are applied. See
<code>"additional_backgrounds"</code> items are displayed and color schemes are applied. See
<code><a href="#properties">properties</a></code> for details on the properties that this object can contain.
</p>
</td>
Expand All @@ -130,11 +127,12 @@ Images should be 200 pixels high to ensure they always fill the header space ver
<tbody>
<tr>
<td><code>theme_frame</code></td>
<td><code>String</code></td>
<td><code>String</code> or <code>Object</code></td>
<td>
<p>
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 (defined by the path to an image asset packaged in the extension) or <a href="#css_gradient_syntax">CSS gradient</a>
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.
</p>
<div class="notecard note">
<p>
Expand All @@ -144,39 +142,53 @@ Images should be 200 pixels high to ensure they always fill the header space ver
</p>
</div>
<p>
Optional in desktop Firefox 60 onwards. Required in Firefox for Android.
Optional in desktop Firefox 60 onwards.
</p>
</td>
</tr>
<tr>
<td><code>additional_backgrounds</code></td>
<td><code>Array</code> of <code>String</code></td>
<td><code>Array</code> of <code>String</code> or <code>Object</code></td>
<td>
<div class="warning">
<p>
<strong>Warning:</strong> The
<code>additional_backgrounds</code> 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.
<code>additional_backgrounds</code> property is experimental. It's

@rpl rpl Jun 30, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

question: do other MDN doc pages often use contractions for forms like It is? As a non native english speaker I personally prefer them to don't use the contraction in docs, but it is something that other MDN doc pages are also doing I'd be fine with the contractions to be used in this page (otherwise I'd prefer to leave those as is).

@rebloor rebloor Jul 2, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rpl Our style guide says: Contractions: Our writing style tends to be casual, so you should feel free to use contractions (e.g., "don't", "can't", "shouldn't"), if you prefer. This is perhaps not the most useful style guidance as it results in a mix of styles, even within the same page. I'm aware of the arguments against contractions to assist non-native English speakers; however, if we are allowing contractions, we should consistently apply them. Perhaps we should request clarification of the style guide to either allow or disallow contractions

accepted in release versions of Firefox, but its behavior
is subject to change.
</p>
</div>
<p>
An array of URLs for additional background images to be added to the
header area and displayed behind the
<code>"theme_frame":</code> 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, each being either the path to an image asset packaged in the extension or <a href="#css_gradient_syntax">CSS gradient</a>, to be added to
the header area and displayed behind the
<code>"theme_frame":</code> 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.
</p>
<p>Optional.</p>
<p>Optional</p>
<p>
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 <code>"properties":</code>.
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 <a href="#properties"><code>"properties":</code></a>.
</p>
</td>
</tr>
</tbody>
</table>

### 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:
Expand All @@ -203,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.

<table class="fullwidth-table standard-table">
<thead>
Expand Down Expand Up @@ -363,7 +368,7 @@ All these properties can be specified as either a string containing any valid [C
<td>
<p>
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
<code>"theme_frame"</code> and <code>"additional_backgrounds"</code>.
</p>
<details open>
Expand All @@ -386,7 +391,7 @@ All these properties can be specified as either a string containing any valid [C
<p>
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 <code>"theme_frame"</code> and
through the items specified in <code>"theme_frame"</code> and
<code>"additional_backgrounds"</code>.
</p>
<details open>
Expand Down Expand Up @@ -1325,6 +1330,25 @@ Additionally, this key accepts various properties that are aliases for one of th
<p>If not specified, defaults to <code>"no-repeat"</code>.</p>
</td>
</tr>
<tr>
<td><code>additional_backgrounds_size</code></td>
<td>
<p><code>Array</code> of <code>String</code></p>
</td>
<td>
<p>Optional</p>

@rpl rpl Jun 30, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: the other entry seems to have a period at the end of the Optional string, let's consider to add it here too for consistency (technically also on the properties description in the first table of the section https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/theme#syntax too).

@rebloor rebloor Jul 2, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The more consistent approach across the entire web extensions documentation set is to not have the period. So I've removed them here.

<p>
An array of values defining the size of the corresponding
<code>"additional_backgrounds":</code> array item. Accepts the same
values as the CSS
<a href="/en-US/docs/Web/CSS/Reference/Properties/background-size"><code>background-size</code></a>
property, such as <code>"auto"</code>, <code>"cover"</code>,
<code>"contain"</code>, or explicit width and height values (for
example, <code>"100px 200px"</code>).
</p>
<p>If not specified, defaults to <code>"auto"</code>.</p>

@rpl rpl Jun 30, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

question: should we mention explicitly what happens if the number of entries do not match the number of entries in the additional_backgrounds property? I assume we use the default, auto, in that case. If that feels like already implied we may not need to specify it but I thought to bring it up to double-check it with you.

@rebloor rebloor Jul 2, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rpl According to Claude, we don't default to auto, rather "The implementation joins the size values as a comma-separated CSS background-size property value. That means standard CSS cycling behavior applies — if additional_backgrounds_size has fewer entries than additional_backgrounds, the size values cycle from the beginning of the array for the extra items. For example, with 3 backgrounds and "additional_backgrounds_size": ["auto", "100px"], the third item gets auto (cycling back to index 0)." Are you able to confirm? If so, it doesn't sound like the behavior that we would expect.

</td>
</tr>
<tr>
<td><code>color_scheme</code></td>
<td>
Expand Down Expand Up @@ -1386,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": {
Expand Down Expand Up @@ -1450,6 +1474,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 -20%, #FFC999 50%" }
]
},
"properties": {
"additional_backgrounds_alignment": ["right top", "left top", "right top"],
"additional_backgrounds_tiling": ["no-repeat", "no-repeat", "repeat-x"],
"additional_backgrounds_size": ["auto", "auto", "auto 144px"]
}
}
```

This results in:

- `background-image1.svg` displaying at the top right, at its natural size.
- `background-image2.svg` displaying at the top left, at its natural size.
- The `linear-gradient` displaying from the top right, tiled horizontally across the header (`repeat-x`), and sized to 144px tall (width is automatic). The gradient transitions from pink (`#FF6BBA`) at the top to peach (`#FFC999`) at the bottom.

## Browser compatibility

{{Compat}}
Expand All @@ -1458,7 +1507,7 @@ In this screenshot, `"toolbar_vertical_separator"` is the white vertical line 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:

Expand Down
3 changes: 2 additions & 1 deletion files/en-us/mozilla/firefox/releases/153/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,9 @@ Firefox 153 is the current [Beta version of Firefox](https://www.firefox.com/en-
- Extensions now require explicit user permission to access `file://` URLs. Previously, access to local files was covered by the "Access your data for all websites" host permission. This change introduces a separate "Access local files on your computer" option in the extension's permissions settings (desktop only), and file access is turned off by default for all extensions, including existing ones. The {{WebExtAPIRef("extension.isAllowedFileSchemeAccess()")}} method now correctly returns `true` if the user has granted file scheme access; previously, Firefox always returned `false`. Additionally, calling {{WebExtAPIRef("devtools.inspectedWindow.eval()")}} on `file://` URLs now requires this permission. ([Firefox bug 2034168](https://bugzil.la/2034168))
- 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))
- Adds `documentId` to a range of WebExtension APIs, including a new {{WebExtAPIRef("runtime.getDocumentId()")}} method, {{WebExtAPIRef("webNavigation")}} events and methods, {{WebExtAPIRef("webRequest")}} events, scripting injection targets, and messaging APIs. See [Work with documentId](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_documentId) for the full list of supported events and methods, along with guidance on using `documentId`. ([Firefox bug 1891478](https://bugzil.la/1891478))
- 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))
Expand Down