Overriding Styles in Firefox Using userContent.css

This article provides a complete overview of how the userContent.css file in the Mozilla Firefox browser allows users to override the default styling of both external websites and internal about: pages. By enabling a hidden configuration preference, creating the stylesheet in the browser profile directory, and utilizing Mozilla-specific CSS rules, users can bypass standard web design constraints and customize their browsing experience.

How the Override Mechanism Works

Web browsers render pages using a cascading hierarchy of stylesheets: browser defaults (user agent styles), user-defined styles, and website styles (author styles). Normally, website styles override user-defined styles.

However, the CSS specification dictates that if a user-defined style includes the !important declaration, it takes absolute precedence over the website's styles—even if the website also uses !important. Firefox reads the userContent.css file at startup and injects its rules into every page load as a user-defined stylesheet, allowing you to force custom CSS onto any webpage.

Step 1: Enable Custom Stylesheets in Firefox

To optimize startup performance, Firefox does not look for the userContent.css file by default. You must manually tell the browser to load it.

  1. Open Firefox, type about:config into the address bar, and press Enter.
  2. Click the button to accept the risk and continue.
  3. In the search bar at the top, type toolkit.legacyUserProfileCustomizations.stylesheets.
  4. Double-click the preference to change its value from false to true.

Step 2: Create the userContent.css File

The file does not exist by default; you must create it inside your specific Firefox profile folder.

  1. Type about:support in the Firefox address bar and press Enter.
  2. Locate the Profile Folder row under the Application Basics section and click the Open Folder button.
  3. Inside this profile directory, create a new folder and name it chrome (use all lowercase letters).
  4. Open the new chrome folder and create a new plain text file named userContent.css (case-sensitive).

Step 3: Override Specific Websites

If you write standard CSS directly into userContent.css, it will apply to every single website you visit. To restrict your CSS rules to specific websites, you must wrap your code in the Mozilla-specific @-moz-document at-rule.

You can target sites using three primary functions inside this rule:

  • domain(): Affects the specified domain and all its subdomains.
  • url(): Affects only the exact web address specified.
  • url-prefix(): Affects any page that begins with the specified address.

Open userContent.css in any text editor and add your rules. Remember to include !important after every property value to ensure it overrides the website's native CSS.

/* Applies to example.com and all its subdomains */
@-moz-document domain("example.com") {
    body {
        background-color: #121212 !important;
        color: #e0e0e0 !important;
    }
    
    .annoying-banner {
        display: none !important;
    }
}

/* Applies only to a specific page */
@-moz-document url("https://www.wikipedia.org/") {
    .central-featured {
        opacity: 0.5 !important;
    }
}

Step 4: Override Internal about: Pages

For security reasons, Firefox blocks standard web extensions (like Stylus or Dark Reader) from modifying internal browser pages, such as the New Tab page, settings, or about:config. Because userContent.css operates natively at the browser level, it bypasses these security restrictions entirely.

You can style internal pages using the exact same @-moz-document syntax by targeting their internal URLs.

/* Changes the background color of the New Tab and Home pages */
@-moz-document url("about:newtab"), url("about:home") {
    body {
        background-color: #1e1e2e !important;
    }
    
    /* Hides the search bar on the New Tab page */
    .search-wrapper {
        display: none !important;
    }
}

/* Modifies the Firefox Settings page */
@-moz-document url-prefix("about:preferences") {
    .navigation {
        background-color: #000000 !important;
    }
}

Applying Your Changes

Firefox only reads the userContent.css file when the application first launches. Whenever you add, remove, or edit rules inside the file, you must save the document and completely restart the Firefox browser for your changes to take effect. To find the exact CSS selectors (classes and IDs) needed for your overrides, right-click on any webpage or about: page, select Inspect, and use the Firefox Developer Tools to examine the page's HTML structure.