Using the Model New Theming API in Firefox

By | December 4, 2017

From highly effective extensions like Stratiform or FT Deep Dark to easy lightweight themes, theming has been fairly well-liked inside Firefox. Now that Firefox Quantum (57) has launched with many efficiency enhancements and a glowing new interface, we wish to bridge the hole with a model new theming API that permits you to transcend primary light-weight themes.

Demo by John Gruen

What are you able to theme?

Before the launch of Quantum, light-weight themes had a restricted set of properties that may very nicely be themed: you may possibly solely add a header picture and set the body textual content shade and background shade. The model new theming API introduces some new properties. The complete record can be discovered on MDN. A primary Theme object seems to be like this:

{ “colors”: { “accentcolor”: “tomato”, “textcolor”: “white”, “toolbar”: “#444”, “toolbar_text”: “lightgray”, “toolbar_field”: “black”, “toolbar_field_text”: “white” }, “images”: { “headerURL”: “” }}

Heres how the above theme is displayed:

Notice how the images.headerURL property is ready to an empty string. It’s because it’s one among three necessary properties: images.headerURL, colors.accentcolor and colors.textcolor.

Finally, one other enchancment to light-weight themes is assist for a quantity of header photos, utilizing the images.additional_backgrounds discipline which takes an array of picture paths. The alignments and tilings of those photos is achieved utilizing properties.additional_backgrounds_alignment and properties.additional_backgrounds_tiling, which soak up an array of background-position and background-repeat values respectively. You may take a glance at the MDN web page for an example. You ought to use a quantity of backgrounds with a view to show curtains on each side of the browser UI, or as a approach so as to add a quantity of thematic indicators (sports/weather/private browsing) within the UI.

Dynamic themes

Lets say you want to introduce an evening mode to your theme. Dynamic themes assist you to do that. They’ve the complete energy of a standard browser extension. To make use of dynamic theming, it’s essential add the theme permission to your manifest.

The browser.theme.update() technique is on the core of this type of theming. It takes in a Theme object as parameter. The strategy will be referred to as anyplace in your background scripts.

For this instance, lets create an extension that switches the theme relying on whether or not its evening or day. Step one is to create a operate in your background script that switches your theme to the day theme or the evening theme:

var currentTheme = ”; const themes = { ‘day’: { photos: { headerURL: ‘sun.jpg’, }, colours: { accentcolor: ‘#CF723F’, textcolor: ‘#111’, } }, ‘night’: { photos: { headerURL: ‘moon.jpg’, }, colours: { accentcolor: ‘#000’, textcolor: ‘#fff’, } }}; operate setTheme(theme) { if (currentTheme === theme) { // No level in altering the theme if it has already been set. return; } currentTheme = theme; browser.theme.update(themes[theme]);}

The above code defines two themes: the day theme and the evening theme, the setTheme operate then makes use of browser.theme.update() to set the theme.
The subsequent step is now to make use of this setTheme operate and periodically test whether or not the extension ought to change themes. You are capable of do this utilizing the alarms API. The code under checks periodically and units the theme accordingly:

function checkTime() { let date = new Date(); let hours = date.getHours(); // Will set the solar theme between 8am and 8pm. if (hours > eight && hours < 20) { setTheme(‘day’); } else { setTheme(‘night’); }} // On begin up, test the time to see what theme to show.checkTime(); // Arrange an alarm to test this regularly.browser.alarms.onAlarm.addListener(checkTime);browser.alarms.create(‘checkTime’, {periodInMinutes: 5});

Thats it for this instance! The complete instance is on the market on the webextension-examples github repository.

Another technique thats not lined by the instance is browser.theme.reset(). This technique merely resets the theme to the default browser theme.

Per-window themes

The dynamic theming API is fairly highly effective, however what if it’s essential apply a distinct theme for personal home windows or inactive home windows? From Firefox fifty seven onwards, it’s potential to specify a windowId parameter to each browser.theme.update() and browser.theme.reset(). The windowId is similar ID returned by the windows API.

Lets make a easy instance that provides a darkish theme to personal home windows and retains different home windows set to the default theme:

We begin by defining the themeWindow function:

function themeWindow(window) { // Test if the window is in personal looking if (window.incognito) { browser.theme.update(, { photos: { headerURL: “”, }, colours: { accentcolor: “black”, textcolor: “white”, toolbar: “#333”, toolbar_text: “white” } }); } // Reset to the default theme in any other case else { browser.theme.reset(; }}

Once thats carried out, we are ready to wire this up with the windows API:; // Theme all presently open => wins.forEach(themeWindow));

Pretty easy proper? The complete instance will be discovered right here. Right here is how the instance looks:

Another add-on that makes use of those capabilities is the Containers theme by Jonathan Kingston, which units the theme of every window to the container of its chosen tab. The supply code for this add-on will be discovered right here.

The VivaldiFox add-on additionally makes use of this functionality to show different web site themes throughout different windows:

Obtaining details about the present theme

From Firefox fifty eight onward, now you can get hold of details about the present theme and look forward to theme updates. Heres why this matters:

This permits add-ons to combine their person interface seamlessly with the customers presently put in theme. An instance of this is ready to be matching your sidebar tabs colours with the colours out of your present theme.

To accomplish that, Firefox fifty eight provides two new APIs: browser.theme.getCurrent() and browser.theme.onUpdated.

Here is a straightforward instance that applies a variety of the present theme properties to the fashion of a sidebar_action:

function setSidebarStyle(theme) { const myElement = document.getElementById(“myElement”); // colors.frame and colors.accentcolor are aliases if (theme.colors && (theme.colors.accentcolor theme.colors.frame)) { = theme.colors.accentcolor theme.colors.frame; } else { = “white”; } if (theme.colors && theme.colors.toolbar) { = theme.colors.toolbar; } else { = “#ebebeb”; } if (theme.colors && theme.colors.toolbar_text) { = theme.colors.toolbar_text; } else { = “black”; }} // Set the ingredient fashion when the extension web page loadsbrowser.theme.getCurrent().then(setSidebarStyle); // Look forward to theme updatesbrowser.theme.onUpdated.addListener(async ({ theme, windowId }) => { const sidebarWindow = await; /* Solely replace theme if it applies to the window the sidebar is in. If a windowId is handed throughout an replace, it implies that the theme is utilized to that particular window. In any other case, the theme is utilized globally to all home windows. */ if (!windowId windowId == { setSidebarStyle(theme); }});

The full instance will be discovered on Github. As you may see within the screenshot under, the sidebar makes use of colours from the presently utilized browser theme:

Another instance is the Tree Fashion Tab add-on which makes use of those APIs to combine its interface with the presently used theme. Here’s a screencast of the add-on working along with VivaldiFox:

Whats next?

There is extra coming to this API! We plan to increase the set of supported properties and polish some tough edges round the finest way themes are utilized. The monitoring bug for the API can be discovered on Bugzilla.

In the in the meantime, we cant wait to see what it is feasible for you to to do with the model new theming API. Please tell us what enhancements you want to see.

Mozilla contributor who cares concerning the net and know-how in general.

More articles by Tim Nguyen

Please check this great service at: or visit FREE SERVICES menu
[Total: 0    Average: 0/5]