Contributors guide on Firefox advanced customization with CSS

Revision Information
  • Revision id: 238884
  • Created:
  • Creator: Danny Colin
  • Comment: Add jscher2000 wonderful website on userChrome.
  • Reviewed: No
  • Ready for localization: No
Revision Source
Revision Content
Warning: CSS customization is intended for developers, not end users.

In addition to the built-in customization feature (see Customize Firefox controls, buttons and toolbars) and themes (see Use themes to change the look of Firefox), advanced Firefox users can also make changes to their browser UI by applying style rules in an optional external file named userChrome.css.

As SUMO contributors, here's what you need to know about Firefox advanced customization using additional CSS file:

What does userChrome.css do?

Firefox’s user interface is built of web-like elements (HTML and XUL elements) and styled using CSS. Users can set Firefox to look for a userChrome.css file at startup, so the rules in the file can restyle various elements of the user interface. For example, custom rules can change colors and sizes of many elements, hide them, or reposition them.

What do users need to know before they use userChrome.css customization?

Users should expect that some of their custom rules will stop working correctly in the future, and in extreme cases, this may cause serious issues with the user interface. Firefox is a work in progress and to allow for continuous innovation, Mozilla cannot guarantee that the styled elements will not change. When new features and new user interface designs are introduced, they often require different HTML and XUL tags, and the styling of these tags will evolve as well. For this reason, Mozilla does not officially support custom style rules.

Where can users get help with custom rules and userChrome.css?

Mozilla's support forum provides peer-to-peer assistance in a very limited basis for these kind of customization. We encourage users with userChrome.css issues to seek assistance and informations through other forums and websites instead, such as userchrome.org, r/FirefoxCSS on Reddit or a community-driven room on our Matrix server.

How to revert Firefox back to its default state?

If Firefox user interface suddenly looks broken after an update, and the users have created a userChrome.css file in the past, they can use Firefox’s Troubleshoot Mode (see Diagnose Firefox issues using Troubleshoot Mode) to quickly disable their custom rules, and see whether that makes any difference. If they would like to undo their customization and restore Firefox to its default UI, Users can use one of the following methods.

Reset Firefox to its default state

Warning: A Firefox refresh removes add-ons and other customizations, such as extensions, extension data, and preference configurations. If you've made accessibility customizations to Firefox, you may need to add them back after refreshing.

Users can reset Firefox to its default state by following the steps at Refresh Firefox - reset add-ons and settings.

Disable and remove userChrome.css

Users can disable and remove their userChrome.css file to be loaded on Firefox startup by following this steps:

  1. Open about:config
  2. Set toolkit.legacyUserProfileCustomizations.stylesheets back to false.
  3. Remove userChrome.css inside the chrome folder of their profile folder. They can find their profile folder by following the instructions from the How do I find my profile? section in Profiles - Where Firefox stores your bookmarks, passwords and other user data