Contributors guide on Firefox advanced customization with CSS

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 through other forums instead, such as 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, they 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.

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