Contributors guide on Firefox advanced customization with CSS

Revision Information
  • Revision id: 229114
  • Created:
  • Creator: Kiki
  • Comment: add warning
  • Reviewed: No
  • Ready for localization: No
Revision Source
Revision Content
Warning: CSS customization is intended for developers, not end users. Please read the following article carefully to understand the risk of doing advanced customization with CSS in Firefox.

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

What does userChrome.css do?

Firefox’s user interface is built of web-like elements (HTML and XUL elements) and styled using CSS. If you set Firefox to look for a userChrome.css file at startup, 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 I need to know before I use userChrome.css customization?

You should expect that some of your 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 elements you styled 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 I get help with custom rules and userChrome.css?

The Firefox user community provides peer-to-peer assistance with userChrome.css modifications on a variety of sites and forums. A popular one is r/FirefoxCSS on Reddit. There's also a community-driven room on our Matrix server

How to revert Firefox back to its default state?

If your Firefox user interface suddenly looks broken after an update, and you have created a userChrome.css file, you can use Firefox’s Troubleshoot Mode (see Use Troubleshoot Mode in Firefox) to quickly disable your custom rules, and see whether that makes any difference. If you would like to undo your customization and restore Firefox to its default UI, you can reset Firefox to its default state by following the steps at Refresh Firefox - reset add-ons and settings.

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.