Contributors guide on Firefox advanced customization with CSS

Contributors Contributors Last updated: 03/02/2022 40% of users voted this helpful
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), Firefox themes (see Use themes to change the look of Firefox and other types of add-ons (see Find and install add-ons to add features to Firefox), advanced Firefox users can also make changes to their browser user interface (UI) by applying style rules with an optional file named userChrome.css.

As SUMO contributors, here's what you need to know about Firefox advanced customization using this 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 information through other forums and websites instead, such as the site, the r/FirefoxCSS forum on Reddit or the community-driven #firefoxcss room on Matrix.

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 in the Refresh Firefox - reset add-ons and settings article.

Disable and remove userChrome.css

Users can disable and remove their userChrome.css file so that it does not load on Firefox startup by following this steps:

  1. Type about:config in the address bar and press EnterReturn.
    A warning page may appear. Click Accept the Risk and Continue to go to the about:config page.
  2. Search for the toolkit.legacyUserProfileCustomizations.stylesheets preference and set it back to false by clicking on Reset Fx71aboutconfig-ResetButton.
  3. Remove userChrome.css inside the chrome folder of the profile folder. To find the profile folder, see the How do I find my profile? section in Profiles - Where Firefox stores your bookmarks, passwords and other user data.

Was this article helpful?

Please wait...

These fine people helped write this article:

Illustration of hands


Grow and share your expertise with others. Answer questions and improve our knowledge base.

Learn More