userChrome_getting_started.md

How to customize Firefox with CSS.

---

Getting Started

Firefox supports advanced customization of its UI with user-defined CSS. This allows virtually unlimited customization of the style of the browser, as well as some very limited functionality customization.

You can define these rules in two files, userChrome.css and userContent.css.

userChrome.css affects the browser's chrome (a general term for a UI). This includes things like the address bar and tabs, as well as the menus (even the context menu).

userContent.css affects the browser's content, that is web content as well as Firefox built-in pages (about: pages) and also extension content. About pages include things like the new tab page (about:newtab), the options page (about:preferences), addons page (about:addons), and so on. You can see a complete list of about: pages at about:about.

Setup

Enable userChrome customization in about:config

• Navigate to about:config in the address bar and accept the risks.

• Search for toolkit.legacyUserProfileCustomizations.stylesheets and toggle it to true (by double clicking on it).

For a visual walkthrough Watch Me Do or Youtube.

Locate and open your profile folder using about:support

• Click on ☰ ➝ Help ➝ "More Troubleshooting Information" or navigate to about:support in your address bar.

• Under Application Basics, click on the the Open Folder button next to "Profile folder". You should now see your profile folder being opened in your file manager.

Some people on on MacOS have had the button open the parent folder of the current profile folder. Make sure the opened folder path matches what is listed in about:support.

Create the folder and its files

• Inside your profile folder, create a new folder named chrome (all lower case) - the chrome folder should end up in a folder that includes stuff like prefs.js and places.sqlite.

• Inside the chrome folder, create two new files, userChrome.css and userContent.css (case sensitive)

• Note: In Windows, you might want to disable the "Hide extensions for known file types" setting in Explorer. Once that's done, simply create a new text file (Right click ➝ New ➝ Text Document), then make sure to replace the .txt file-extension with .css

Add some content to files

Open userChrome.css in your preferred text editor such as Notepad, and add styling rules you wish to use. For example:

panelview,  
.panel-arrowcontent{ 
  background: #15141a !important;  
  color: #afafab !important;
}

Restart Firefox and now you should see that the Hamburger menu has a dark grey background with light grey text.

Note: Make sure to save userChrome.css and userContent.css as plain text files with no rich text formatting.

Note: Firefox only loads userChrome.css and userContent.css on startup. Thus, you must restart Firefox for any changes to apply.

Note: about namespaces. Around the web you might encounter guides saying something along the lines of "xul namespace line MUST be the first line" - it could look like this:

/* MUST be the first line, don't edit! */
@namespace url("http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul");

Pay no attention to such instructions - they are leftovers from ancient times. The xul namespace declaration has a specific purpose, but you are very likely to shoot yourself to the foot if you use it. The reaon being that Firefox nowadays uses lots of html elements and so if you add that default namespace declaration then none of your custom rules affect those html elements.

Live-editing userChrome.css

If you're writing the styles yourself, you can set up browser toolbox and edit the files directly in it without having to restart Firefox for changes to apply. (You still need to restart Firefox when creating userChrome.css). On top of being able to live-edit userChrome.css, the browser toolbox is essential in figuring out how to add custom styling to various parts of Firefox.

You can find userChrome.css in the browser toolbox like this:

1. Open browser toolbox
2. Activate the Style Editor tab of the toolbox
3. Locate userChrome.css in the sidebar list of all the stylesheet

Unfortunately step 3 can be rather tedious since there are hundreds of stylesheets in the list. And the location of userChrome.css in the list depends on various things, such as how much code is inside userChrome.css. In practice it might be easier to use the inspector tab of the toolbox to inspect an element you know your userChrome.css is affecting and find userChrome.css via that.

Highlight userChrome.css in browser toolbox

Another way to help locate userChrome.css in the list of files is to create separate userContent.css for the browser toolbox process, and add style which highlights the name of userChrome.css (and any other name you wish to highlight). Browser toolbox has its own separate profile inside the main profile in a folder "chrome_debugger_profile". Since you cannot access about:config in browser toolbox itself, you must instead edit its prefs.js directly to change prefs.

0. Close browser toolbox
1. Create new chrome folder inside "chrome_debugger_profile"
2. Create userContent.css inside said chrome folder (note: userContent.css)
3. Open prefs.js of the debugger profle in text editor and make sure it has line: user_pref("toolkit.legacyUserProfileCustomizations.stylesheets", true); If it doesn't just create it at the end and save file.
4. Add the following content to userContent.css of chrome debugger profile:

/**/

label[value="userChrome.css"]{
  background: #f00 !important;
  color: #fff !important;
  padding-block: 0.5em !important;
}

Afterwards, when you open browser toolbox, the filename of userChrome.css should be highlighted in red making it much easier to spot it in the list of styles.