What Is userChrome.css and How Does It Customize Firefox?

Updated

userChrome.css is a stylesheet file that Firefox loads at startup to restyle its own interface — the toolbars, tabs, address bar, menus, sidebars, and window chrome. It is not a normal website stylesheet: it only works when placed in a specific profile folder and when a Firefox setting (toolkit.legacyUserProfileCustomizations.stylesheets) is enabled. Through it, and through community hubs like FirefoxCSS-Store, you can make Firefox transparent, move tabs to the side, shrink the toolbar, or rebuild the layout entirely — without touching Firefox's source code.

How Firefox applies userChrome.css

Firefox's interface is built with XUL and styled with CSS internally. The userChrome.css file is loaded after the browser's built-in styles, so rules you write can override defaults.

The mechanism is straightforward:

  1. Firefox looks for a chrome folder inside your active profile directory.
  2. If userChrome.css exists there and the legacy stylesheet preference is enabled, Firefox parses it at startup.
  3. Your selectors target internal UI elements (for example #nav-bar, #TabsToolbar, #urlbar) and your declarations override the shipped styling.

Because the file is read at startup, changes require a restart to take effect. There is no live reload built in.

The preference that enables it

Since Firefox 69, userChrome.css is ignored unless you set toolkit.legacyUserProfileCustomizations.stylesheets to true in about:config. Without this, the file is simply not loaded — a common reason a theme appears to do nothing.

What you can actually change

The FirefoxCSS-Store community hub lists 128 themes across 258 tags, with 43,611 stars across theme repositories. That tag vocabulary is a useful map of what userChrome.css can do. Recurring categories include:

Category Example tags What it changes
Transparency and blur transparent, translucent, glassmorphic, vibrancy, mica Window and toolbar backgrounds, often paired with OS-level blur
Tab layout vertical-tabs, tree-style, sidebery, tabs, one-line Tab position, orientation, and grouping
Density compact, minimal, minimalist, one-line, oneliner Toolbar height, padding, hidden elements
Color schemes catppuccin, gruvbox, nord, dracula, amoled, dark Palette applied across the UI
Platform mimicry macos, gnome, safari, opera-gx, arc, fluent Makes Firefox resemble another browser or OS
Behavior auto-hide, autohide, hovercards, gestures Elements that appear on hover or interaction

Named themes in the store illustrate the range: Firefox-Σigma, LIQUID GLASS, LUXE, Fully Transparent Theme, and Classic Theme 2011. Some, like Pro-Fox, are hosted in their own GitHub repositories and linked from the store rather than living inside it.

A theme is usually a folder containing userChrome.css plus supporting files — images, fonts, or additional stylesheets — and often a user.js or about:config snippet for required preferences.

userChrome.css vs. userContent.css

These two files are often mentioned together but affect different things:

  • userChrome.css styles Firefox's own interface — the browser chrome. Tabs, toolbars, menus, the address bar, sidebars.
  • userContent.css styles web content — the pages you visit. It can restyle internal pages like about:newtab and about:config, and apply CSS to websites.

They live in the same chrome folder and are enabled by the same preference, but a rule written for one will not affect the other. A theme that changes the look of the new tab page is typically using userContent.css; a theme that makes the toolbar transparent is using userChrome.css.

Limitations and compatibility

userChrome.css is powerful but fragile, and it is worth understanding why before investing time in a theme.

It depends on internal selectors. Firefox's UI markup is not a public API. When Mozilla refactors the browser chrome, IDs and class names can change, and a theme that worked in one version may break in the next. Themes tagged with version numbers (v89, v91) reflect this — they were written against a specific era of Firefox.

It is unsupported. Mozilla does not guarantee that userChrome.css will keep working, and the legacy preference exists specifically to gate this kind of customization. There is no official support channel for a broken theme.

It cannot change everything. Some behaviors are controlled by JavaScript in privileged browser code, not CSS. Themes that need real behavior changes — like a fully reimplemented tab system — often ship a companion extension (Sidebery and Tree Style Tab appear frequently in the store's tags) or a user.js file.

Performance is usually fine. CSS-only changes are cheap. Heavy use of blur, transparency, and large background images can cost some rendering performance, particularly on lower-end hardware.

Choosing a theme that will last

Because breakage is version-dependent, the practical signals are:

  • Recently updated — the store sorts by "Recently updated" and "Latest shared," which surfaces themes still being maintained.
  • Star count — the store tracks stars across theme repositories, so a well-starred theme is more likely to have an active maintainer and issue reports when Firefox changes.
  • Scope — a theme that only tweaks colors and spacing is less likely to break than one that restructures the tab strip.
  • A linked repository — themes hosted on GitHub (like Pro-Fox) give you a place to check recent commits and open issues before installing.

Where FirefoxCSS-Store fits

FirefoxCSS-Store is a discovery layer, not a runtime. It indexes community themes, tags them, and links to their sources. You browse or search by tag, open a theme's page, and follow its installation instructions — which typically means downloading the files, placing them in your profile's chrome folder, and setting the legacy stylesheet preference.

If you want to understand what userChrome.css can do before writing any yourself, browsing the store's tag list is a faster survey than reading documentation: it shows the actual range of what people have built, from a single tweak to a complete interface replacement.