# firefox-csshacks: userChrome.css Styles for Firefox, Installed by Git Clone

> A repository of self-contained CSS files that restyle Firefox's browser UI and content pages, loaded through userChrome.css and userContent.css. The setup is a preference change plus a git clone into your profile folder, and the main cost is that a Firefox update can break any rule you rely on.

**MrOtherGuy/firefox-csshacks** — Collection of userstyles affecting the browser

- Repository: https://github.com/MrOtherGuy/firefox-csshacks
- Stars: 4,525 · Forks: 366
- Language: CSS
- License: MPL-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/mrotherguy-firefox-csshacks

## What firefox-csshacks actually changes

Firefox's own theming surface covers colors and a few toolbar arrangements. It does not cover the shape of the tab close button, the motion of a loading indicator, or the width of the navigation toolbar. Those are internal widget styles, and the only supported way to reach them from outside the browser is the legacy user stylesheet mechanism. This repository is a library of small CSS files that target those internals, one concern per file, so you can take the tab close button rule without taking anything else.

The audience is narrow and specific: people who already know they want to alter Firefox's chrome, and who are comfortable editing CSS and restarting the browser to see the result. The README states plainly that stylesheets are tested only on Windows 10 and to a lesser amount on Linux, and that behavior may be wrong on OSX and Windows 7, particularly when native widgets such as the window titlebar or window control buttons are being styled. That is a real constraint, not a disclaimer. If you are on macOS and your intended change touches the titlebar, expect to debug it yourself.

## How the loading mechanism works

Two files matter. Firefox loads userChrome.css into the browser UI and userContent.css into content documents such as web pages and built-in or extension pages. Both are read from the chrome folder inside the profile, and neither the folder nor the files exist by default, so nothing happens until you create them.

The repository is split into chrome/ and content/ sub-folders along the same line. The README says using a chrome style in userContent.css is not a technical requirement but that the styles generally will not do anything in the wrong context, which is a fair description of CSS that targets selectors that only exist in one of the two documents.

Import order is the part people get wrong. All @import rules must be placed before any other rules in the file, including @namespace rules, and the order of imported files matters as much as the order of rules within a single file. That is standard CSS cascade behavior, but it bites here because you are stacking a dozen independent files that were written without knowledge of each other. The README notes the stylesheets are mostly self-contained and can be mixed somewhat freely, with no promises about compatibility with third-party styles. When a style depends on another, the dependency is noted at the top of the file that requires it, so the file header is the place to look before importing.

## Installing firefox-csshacks and importing your first style

First enable the preference. Open about:config and set toolkit.legacyUserProfileCustomizations.stylesheets to true. Until this is true, Firefox will not look for either stylesheet, no matter where you put them.

Next find the profile folder. With Firefox running, open about:support and look for the Profile folder row near the top, which has an Open folder button beside it. The README warns that on some Firefox versions that button opens the parent profiles folder that houses all your profiles, in which case you navigate into the specific one you want. The reliable check is the contents: the real profile folder contains prefs.js and places.sqlite.

The README calls the git route the preferred way to do things, because it makes updates easier and makes organizing multiple styles easier. It assumes you have a git client and no existing chrome folder in the profile. Open a terminal, cd into the profile folder, and clone the repository under the name chrome.

```bash
git clone https://github.com/MrOtherGuy/firefox-csshacks.git chrome
```

That creates a chrome folder in the profile containing the repository contents. If you already had a chrome folder, the README says to rename it before cloning and then copy the contents of the old folder into the new one afterward.

Now create userChrome.css. The repository ships userChrome_example.css, and the README suggests making a copy of it and renaming the copy. Inside it, pull in individual styles with @import, keeping every import above any other rule.

```css
@import url(chrome/tab_close_button_always_on_hover.css);
@import url(chrome/tab_loading_progress_throbber.css);
@import url(chrome/button_effect_scale_onclick.css);
```

Those three filenames come from the example in the README. The paths are relative to the chrome folder, not to the profile root, which is why they start with chrome/. Restart Firefox and the changes take effect. If nothing changes, check the file extension first: the README notes that a file manager hiding extensions can leave you with userChrome.css.txt, which Firefox will not load.

## Keeping local edits while updates replace the styles

The reason the README prefers cloning over copy-paste is update behavior. Running git pull inside the chrome folder replaces the repository's files with current versions. It does not replace your userChrome.css, because that file is yours and is not part of the tracked set in the way the style files are. So the intended workflow is to leave the imported style files untouched and put your own rules at the bottom of userChrome.css, after the imports. Your modifications survive updates; the upstream styles get refreshed.

The manual alternative, copying the contents of individual .css files directly into userChrome.css, is described in the README as simple for better and for worse. The worse is exactly this: once upstream fixes a selector, you have no clean way to take the fix, because your copy has diverged. For a one-off tweak you never intend to maintain, that is fine. For anything you will still be using in six months, it is the wrong choice.

There is a helper script, add_style.py, at the top level of the repository, alongside tags.csv and index.html. The README does not document its usage, so treat it as something to read before running rather than a supported installer.

## Where firefox-csshacks breaks, and why it will again

These styles target Firefox's internal markup and CSS variables. Firefox changes that markup between releases. A selector that matched a toolbar button in one version can match nothing in the next, and the failure is silent: the style simply stops applying, with no error anywhere. The README's own testing note, Windows 10 primarily and Linux to a lesser extent, tells you the maintainers cannot verify every platform, so a break on your OS may go unnoticed upstream.

The second failure mode is interaction between styles. The files are mostly self-contained, but mostly is doing real work in that sentence. Two styles that both restyle the same element, imported in the wrong order, produce a result neither author intended, and the cascade gives you no warning. The README's advice to import each style unmodified and apply your own changes afterward is the practical mitigation.

The third is the profile folder itself. If you edit the wrong profile, or create userChrome.css in the profiles parent directory instead of the profile, Firefox loads nothing and you get no feedback about why. This is where most first attempts die.

Finally, this is the wrong tool if you want a supported extension point. The preference is named legacy for a reason. If your requirement is a theme you can ship to other people through addons.mozilla.org, userChrome.css is not that mechanism.

## How this differs from a Firefox theme or extension

A Firefox theme, distributed as an add-on, changes a defined set of colors and images through the theme API. It installs in one click, it survives browser updates because Mozilla maintains the API, and it cannot reach into widget internals at all. firefox-csshacks does the opposite on every axis: it installs by cloning into your profile, it can break on any release, and it can restyle things the theme API never exposes, such as the tab loading indicator or the click animation on toolbar buttons.

The middle option is a userstyle applied through an extension that injects CSS into pages. That covers the content/ side of this repository reasonably well, since those styles target web documents. It does not cover the chrome/ side, because browser UI is not a page the extension can reach. If your goal is restyling websites rather than Firefox itself, this repository is the wrong layer entirely.

So the choice is not which is better but which layer your change lives in. Anything expressible as a theme belongs in a theme. Anything that requires selecting an internal element belongs here, with the maintenance burden that implies.

## Licence and the maintenance you are signing up for

The repository is under MPL-2.0. That is a file-level copyleft licence: modifications to files covered by it stay under the same licence when redistributed, while you can combine those files with your own work under other terms. If you fork a style file and publish your version, keep the MPL notice on that file. Nothing here is legal advice, and if you plan to redistribute a modified collection, read the licence text in the LICENSE file at the top level rather than a summary.

The practical cost is not the licence, it is the update loop. The last push to this repository was on 2026-09-21, two days before this writing, so the collection is being touched. That does not mean any particular style you adopt is current for your Firefox build. The workflow the README enables, git pull in the chrome folder, is what keeps you close to upstream, and it only works if you kept your own rules out of the imported files. Budget for a look at your userChrome.css after each Firefox major release, because that is when internal markup tends to move.

## Conclusion

Adopt it if you want a Firefox UI change that no theme or extension exposes, and you are willing to keep a chrome folder under version control and re-check it after browser updates. Do not adopt it if you need a supported, stable theming API, or if you cannot find your real profile folder. Before importing anything, set toolkit.legacyUserProfileCustomizations.stylesheets to true, confirm the profile folder contains prefs.js and places.sqlite, and clone the repository as chrome rather than copying files by hand.

## FAQ

### How do I enable userChrome.css in Firefox for firefox-csshacks?

Go to about:config and set toolkit.legacyUserProfileCustomizations.stylesheets to true. Firefox will then try to load userChrome.css and userContent.css from the chrome folder inside your profile, which you have to create yourself.

### Where do I put the firefox-csshacks files in my Firefox profile?

Firefox loads userChrome.css from <profileFolder>/chrome/userChrome.css, and the chrome folder does not exist by default. The README's preferred approach is to cd into the profile folder and clone the repository with the target name chrome, then import individual style files from there.

### Why does my firefox-csshacks style have no effect after I restart Firefox?

Check the filename first: if your file manager hides extensions, you may have created userChrome.css.txt, which Firefox will not load. Also confirm you are in the real profile folder, which should contain prefs.js and places.sqlite, and that every @import sits above all other rules in the file.

### How do I update firefox-csshacks without losing my own CSS changes?

Run git pull inside the chrome folder. It replaces the repository's style files with current versions but does not replace your userChrome.css, so custom rules you put in that file after the imports are preserved.

### Do firefox-csshacks styles work on macOS or Windows 7?

The README states the stylesheets are tested only on Windows 10 and to a lesser amount on Linux, and that most should also work on OSX and Windows 7 but behavior may be wrong, especially when native widgets such as the window titlebar or window control buttons are being styled.

## Sources

- [Issues](https://github.com/MrOtherGuy/firefox-csshacks/issues)
- [License: MPL-2.0](https://github.com/MrOtherGuy/firefox-csshacks/blob/master/LICENSE)
- [MrOtherGuy/firefox-csshacks on GitHub](https://github.com/MrOtherGuy/firefox-csshacks)
- [README](https://github.com/MrOtherGuy/firefox-csshacks/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mrotherguy-firefox-csshacks