How to customize Firefox UI - step-by-step tutorial

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.

Teaser

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:

about:support page

userChrome.css file

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:

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.

@namespace url("http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul");

This will allow you to use any legacy elements and declarations.

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.

Debug tools

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.

UI, click to enlarge

Here are the (magnificent) seven important elements:

  1. #navigator-toolbox - This is the frame containing the page navigation + tab bar.
  2. #nav-bar - This is only the lower half of the navigator-toolbox (the bottom section).
  3. .tabbrowser-tab[selected="true"] - This is the active tab element. Notice the state (selected, true).
  4. .tabbrowser-tab:not([selected="true"]) - This is an inactive tab.
  5. .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.
  6. #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.
  7. #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:

.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;
}

Colors

The code below, when added to userChrome.css will do the following:

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

#navigator-toolbox {
  margin-left: 2px !important;
}

Navigator margin

Then, there's more ...

The code below, when added to userChrome.css will do the following:

#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.

You may also like: