Updated: December 10, 2021
Over the years, lately more often than before, I was forced to make changes to how Firefox looks and behaves on my machines. Previously sane defaults were changed, almost arbitrarily, bringing about functional and aesthetic inefficiencies to my workflow. Australis and Proton are good examples of the said phenomenon.
Recently, I published two fairly detailed guides explaining how to undo the gray-on-gray looks in Firefox 91 onwards. In both cases, I relied on my prior knowledge of the Firefox UI. I realized that for many people, the instructions may be too cryptic. So I decided to make a generic guide on how to customize the Firefox UI, so that if you want to do the same exercise, it won't be too hard to follow.
The basics
The Firefox UI is - in a way - like a Web page. It is defined by a series of stylistic rules embodied in a Web-based language called CSS. This is much like any site. Say, dedoimedo.com, what you see and read is text, but the definitions on how wide the page will be, the color of the font, the spacing of paragraphs, and similar, are all set using CSS files. Similarly, Firefox is styled the same way.
You can override the default rules by creating your own. This is done by adding a new file to your Firefox profile. Inside the file, you create (add) new rules that will affect existing visual elements in the Firefox UI. This is how it's done:
- Open Firefox, type about:support in the address bar.
- On the page that opens, locate the "Profile Folder" line in the table that is displayed. Click on the Open Folder button. This will launch your file explorer (whatever the operating system you're using), and point to the location of your Firefox profile. Please note, Firefox profiles are unique to every user, so you need to make changes for each user separately.
- Now that you know the location of your Firefox profile, create a backup! You can even do a simple manual copy of the entire folder and all of its contents. This way, if something goes wrong, you can restore things to your pristine, vanilla baseline. Do this before any major change.
- In the Firefox profile folder, create a folder (if it does not exist) named chrome (lowercase).
- Navigate into this folder, and here create a file named userChrome.css (notice the lower/uppercase).
- Open this file in a text editor.
By default, the file will be empty and contain nothing. We will now populate it with CSS directives, which will override the look (and behavior) of different Firefox elements. I've done this many times before, so you can refer to some of these guides as a baseline for the workflow. For instance:
Additional groundwork
To make the changes effective, we need several more things:
- Type about:config in the address bar. Accept any warnings to proceed.
- In the search box on the about:config page, search for legacy. The following preference should show up:
toolkit.legacyUserProfileCustomizations.stylesheets
Double-click on it to toggle its state from false to true. This will allow Firefox to use your custom modifications and apply them to the browser. Without this preference toggled, there will be no UI changes.
- In the userChrome.css file, which is currently empty, add the following text to the top:
@namespace url("http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul");
This will allow you to use any legacy elements and declarations.
- Finally, you DO NEED some basic understanding of CSS and how it works. Without this, you will struggle to get the concepts explained here. Things like classes, identifiers, the whole concept of CSS hierarchy and precedence of rules, and such like. I'm afraid there can't be any magical shortcuts.
Firefox UI layout
Now we have the core ingredients to get things working. Next, we need to familiarize with the UI. In my tutorials (linked above), I used things like.tab-background, #searchbar, #navigator-toolbox, and more. You may rightfully wonder, how do I know what these are, and where do I find that information?
The answer is not so simple, I'm afraid ...
One, you need reference guides. Two, you can use Firefox's built-in Browser Toolbox, which lets you pick elements, and identify them. This is somewhat hard work, mind. First, click on the browser's menu > More Tools > Web Developer Tools. Then, when this menu opens, click on the three-dot element to the far right (another menu) > Settings. Or press F1. Here, you will need to select the last two options in the right column: Enable browser chrome ... and Enable remote debugging. Not very intuitive. And let's not rant about the use of hamburger and three-dot menu for two different things in the same UI.
Another option is just a quick, dirty crash course from me, with focus on just the most important UI elements. Which is why I made this annotated screenshot, pointing out the elements I changed in my Proton guides.
Here are the (magnificent) seven important elements:
- #navigator-toolbox - This is the frame containing the page navigation + tab bar.
- #nav-bar - This is only the lower half of the navigator-toolbox (the bottom section).
- .tabbrowser-tab[selected="true"] - This is the active tab element. Notice the state (selected, true).
- .tabbrowser-tab:not([selected="true"]) - This is an inactive tab.
- .tabbrowser-tab[usercontextid] - This is a container tab (if you use the containers add-on). Please note that for items 3-5, you should also be aware of the following element - a class called .tab-background, which specifies the background area of the tab(s). We will use it in conjunction with the tab-browser-tab* declarations above shortly.
- #urlbar - This is the address bar. Note that there's also #urlbar-background, an identifier that is similar to the tab background element we introduced earlier, and which serves a similar purpose. Once again, we will see the necessary examples very soon.
- #searchbar - This is the search box, if you use it.
Things are a bit more complicated than that, of course, but now, you can begin to understand where we're going with this. I think the best solution is to simply demonstrate with a handful of examples, so you understand what gives.
Some basic examples
The code below, when added to userChrome.css will do the following:
- For the active tab, it will set the borders for the tab's large square background piece.
- The top border will be 3px thick, while the left and the right will be only 1px thick.
- They also have different colors.
- The side borders have 30% transparency.
.tabbrowser-tab[selected="true"] .tab-background {
border-left: 1px solid rgba(0, 0, 0, 0.3) !important;
border-right: 1px solid rgba(0, 0, 0, 0.3) !important;
border-top: 3px solid #0a84ff !important;
}
The code below, when added to userChrome.css will do the following:
- For inactive tabs, it will configure the tab background (the large square canvas of the tab) in the following manner: set the actual background color to a mix of current color (system accent color) and transparency layer, using the sRGB color space, and with the system accent color set to just 5% opacity. Basically, the tabs will be pretty much transparent and match your browser's native color.
- Create a very thin 1px (black) border with 30% opacity. The !important clause means your rule will take precedence over any other rule that applies to the same element.
.tabbrowser-tab:not([selected="true"]):not([multiselected="true"]) .tab-background
{
background-color: color-mix(in srgb, currentColor 5%, transparent);
border: 1px solid rgba(0, 0, 0, 0.3) !important;
}
The code below, when added to userChrome.css will do the following:
- It will slightly indent (push inwards) the tabs by adding a 2px margin on the left side. In other words, it will create a tiny bit of extra distance between the tabs and the browser's window edge.
#navigator-toolbox {
margin-left: 2px !important;
}
Then, there's more ...
The code below, when added to userChrome.css will do the following:
- It will set the background of the urlbar to pure white, with a thin 30%-opaque border than matches the accent color of the active tab (specified earlier). You have full artistic freedom here.
#urlbar-background {
background-color: white !important;
border: 1px solid rgba(10, 132, 255, 0.3) !important;
}
Of course, there's way more! But these examples should get you going, I believe.
Conclusion
That was fairly complicated, I admit. I wish there was a simpler way to edit the Firefox UI, but unfortunately, if you're not happy with Firefox's default looks, and you want to alter them beyond the basic customization available, you will need CSS knowledge, CSS files, and a bunch of rules. This guide outlines how you can achieve that, without going into every specific detail of the browser's interface.
I am fully aware that this isn't a trivial task. CSS looks "easy" to those who know how to use it, but it also creates aversion, justifiably, with ordinary people seeking simple ergonomic solutions. I believe the right way is to actually invest a little bit of time and master this lingo, as it gives you the freedom to make the necessary adjustments to the UI, without relying on arbitrary decisions out there somewhere. I wish Mozilla was making better choices, but hey, even with all this nonsense piled into Firefox, it's still the best browser, it allows you to change the interface, and it's the one browser you should use on your desktop and mobile. It's the only thing that makes the Internet still barely usable, and you will not like the future without Firefox. So grab the CSS, get rid of the annoyances, and continue using Firefox. We're done here.
Cheers.