What is userChrome.js?

Updated April 18, 2020; Originally posted by jscher2000 on November 25, 2017.

The subject of this site is the userChrome.css file and style recipes that can modify the appearance of Firefox's user interface. However, style rules cannot change the fundamental behavior of user interface features, and historically userChrome.css has not been able to override certain built-in style rules marked !important. If you are intent on making deeper changes, and you can't find a compatible extension, one option to consider would be applying scripts directly to the interface, like the Legacy extension userChromeJS made possible before Firefox 57.

SAFETY FIRST! Unlike style rules that mess up the interface a bit, scripts implemented through userChrome.js have the potential to do anything that a Legacy extension could do. Please exercise great caution in adding scripts to your Firefox as they may not have gone through any kind of review process to screen for malicious code.

How it Works

Autoconfig File

At startup, Firefox checks for JavaScript files in the program folder under /defaults/pref. An Autoconfig file — which may be named autoconfig.js, local-settings.js, or whatever.js — directs Firefox to another JavaScript file, sometimes but not always named mozilla.cfg, that contains the actual script code. This Autoconfig mechanism is most often used by companies to preconfigure or lock down Firefox, but it has wide ranging applications. As Mike Kaply reminds us in his 2012 series on the topic, "Autoconfig files are Javascript files that have full access to all components of Firefox." See: Customizing Firefox – Advanced Autoconfig Files. Mozilla Support has some documentation here: Customizing Firefox Using AutoConfig.

By placing a config-prefs.js file in /defaults/pref, and three other files in suitable locations, Firefox can load and run the basic functionality of the userChromeJS extension. The installation procedure is set forth at https://github.com/xiaoxiaoflood/firefox-scripts. There are existing repositories of scripts in at least three locations, and more are likely to emerge:

XBL Binding (obsolete in Firefox 72+)

The gHacks Tech News site ran an article in November 2017 about how you can deploy the power of userChrome.js in Firefox Quantum. The featured example involves using the Firefox-specific -moz-binding style property in the userChrome.css file to sneak in the modification:

toolbarbutton#alltabs-button {
  -moz-binding: url("userChrome.xml#js");

The accompanying userChrome.xml file directs Firefox to load the userChrome.js file, where you would add your scripts. Source: https://github.com/nuchi/firefox-quantum-userchromejs via Run userchrome.js scripts in Firefox 57 or newer. Copyright (c) 2017 Haggai Nuchi. Available for use under the MIT License: https://opensource.org/licenses/MIT.

I recently saw another example, but haven't tried it myself. The author of the Classic Theme Restorer extension has posted an extensive library of style rules files, and one of them binds an XML file which can restore the old search bar from before Firefox 34. In userChrome.css, you can optionally @import oldsearch.css which binds oldsearch.xml, which contains the structural elements and scripts. (If you don't download the whole package, you'll need to fix up the paths.)

Needless to say (but I'll say it anyway), any use of these approaches is at your own risk.

Share Your Experience!

If you try any of these solutions, please post comments using the FEEDBACK button in the bar at the top of the page (you can be anonymous if you like). Let me know how it went, and let others know if you recommend particular scripts.