# WaveFox: a Firefox userChrome stylesheet you edit by hand > WaveFox Nova is a CSS theme for Firefox that ships as a chrome folder you drop into your profile, with behaviour controlled through about:config preferences named WaveFox.HorizontalTabs, WaveFox.VerticalTabs, and WaveFox.Toolbar. Two lines are maintained at once, one for current Firefox and one for the ESR branch, and the ESR line has a different feature set. **QNetITQ/WaveFox** — Firefox CSS Theme/Style for manual customization - Repository: https://github.com/QNetITQ/WaveFox - Stars: 1,250 · Forks: 53 - Language: CSS - License: MIT - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/qnetitq-wavefox ## Two branches, two different products The WaveFox repository carries two maintained lines and they are not the same thing with different numbers. The Nova line, currently at v0.8.158, requires Firefox 158 and Windows, macOS, or Linux. The ESR line, currently at v1.99.153, requires Firefox 153 ESR. The numbering tells the story: the ESR branch is at 1.99 while the Nova branch is at 0.8, because they were versioned independently. The release history shows the cadence of each. WaveFox Nova v0.8.158 was published on 2026-10-12, and the ESR line v1.99.153 came out on 2026-07-04, with v1.8.140 for Firefox 140 ESR back in June 2025. The last push to the repository was on 2026-10-12, so the Nova line is where the active work is. The functional difference matters more than the version numbers. The Nova line enables an extra about:config key, browser.nova.enabled, alongside toolkit.legacyUserProfileCustomizations.stylesheets, and it has a set of features the ESR line does not. There is a whole optional section under the Nova line that the ESR line does not have: the tests options, the tab shapes with a Mode setting, the cross-platform system theme options that work on Windows, Linux, and macOS, and the Firefox 158 tab behaviour that puts tabs one with the browser toolbar. So this is not a single theme with two version numbers. It is a current-release theme with a broader feature set and a separate ESR theme that is a subset. Anyone on ESR should read the ESR section, not the Nova one, and the difference in the about:config steps reflects that. ## Installing it is copying a folder and flipping two keys The installation is the same for both lines and takes two steps. You download the chrome folder and put it in your user profile folder. Then you go to about:config and activate the key toolkit.legacyUserProfileCustomizations.stylesheets, and on the Nova line also browser.nova.enabled. That is the entire mechanism, and it is worth understanding what it implies. This is a userChrome.css stylesheet, which is Firefox's own supported extension point for restyling the browser chrome. The toolkit.legacyUserProfileCustomizations.stylesheets preference is what allows a userChrome stylesheet to be loaded at all in modern Firefox, and it is off by default for good reason, since a malformed stylesheet can break the browser interface entirely. The project also publishes a WaveFox Nightly branch alongside the release tags, and the download links are a Firefox download, the WaveFox releases page, and the Nightly branch. The project is MIT licensed, the primary language is CSS, and the default branch is main. The repository is correspondingly small, with a chrome/ directory holding the stylesheets, a README, a LICENSE, and the .github directory. There is no build step and no package manager, which is the point. You take the CSS as it is and edit it, and the project description says it is a theme for manual customization. ## The options are about:config keys, not a settings dialog This is the part that makes WaveFox different from a normal theme. There is no preferences pane. Every behaviour is a preference you set in about:config, and the preferences are named with a WaveFox prefix so they are greppable. The structural ones come first. WaveFox.HorizontalTabs.AttachedTabs is set to true, and under it WaveFox.HorizontalTabs.AttachedTabs.Shape takes a value of 1 to 4, with a further Shape.Mode of 1 or 2. That setting makes tabs one with the browser toolbar, and the README notes it depends on the corner rounding settings or on custom tab shapes. The visual ones are separate. WaveFox.Toolbar.Roundings controls the rounding of browser bar elements, with five levels. WaveFox.HorizontalTabs.Tabs.Separators takes 1 or 2. WaveFox.HorizontalTabs.Tabs.Shadows turns the tab bar shadow on, and in the ESR line the shadow has its own mode key, WaveFox.HorizontalTabs.AttachedTabs.Shadows.Mode, set to 1. There is also WaveFox.HorizontalTabs.FloatingTabs.TabsBelowURL, and WaveFox.HorizontalTabs.FloatingTabs.OneLine for a single-row floating tab strip. The spacing control is WaveFox.HorizontalTabs.AttachedTabs.DragSpace, with three levels, which is how much room you leave to drag a tab. The icons are a separate concern. WaveFox.Icons takes 1 or 2, and it needs the svg.context-properties.content.enabled key to work, which the README marks as a required key. The icon set is third-party code from firefox-csshacks or Lepton, and the author says the code will be updated according to the original source. The ESR line also exposes a long list of per-element icon keys, such as userChrome.icon.panel_full, userChrome.icon.library, userChrome.icon.global_menu, and userChrome.icon.menu.full, and those keys are only relevant for the second icon option. The transparency options are platform-specific, and the ESR line shows the split clearly. On Windows 10 you install DWMBlurGlass and then set WaveFox.Windows10.Transparency.Enabled along with browser.tabs.inTitlebar greater than 1. On Linux there is WaveFox.Linux.Transparency.Enabled, the same browser.tabs.inTitlebar requirement, and a further key, WaveFox.Linux.Transparency.TextColor.White.Enabled. The Nova line replaces both with WaveFox.HorizontalTabs.OS.SystemTheme and WaveFox.VerticalTabs.OS.SystemTheme, which require an OS with transparency support and work only with the system theme. ## The third-party code and the experimental section Two passages in the README are worth separating out, because they describe the project's boundaries honestly. The first is the icons. The icon set is third-party code, and the author says he will update this code according to the original source. That is a maintenance arrangement rather than a reimplementation, and it means the icon work is inherited rather than authored, with the upstream project as the source of truth for how the icons behave. The second is the optional tests section, which appears only under the Nova line and carries a clear disclaimer. It says these are very rough options, and there is no guarantee they will make it into the final release. The keys in it are WaveFox.VerticalTabs.Tests with a value of 1 or 2. That disclaimer is the honest boundary of the project. The stable feature set is the tab layout, the toolbar, the icons, the rounding, the separators, the shadows, and the transparency. The vertical tab experiments are flagged as provisional. The layout model itself is worth spelling out, because it is the main thing the theme does. There are horizontal tabs and vertical tabs, and the vertical tab line has its own namespace, WaveFox.VerticalTabs, with its own OS.SystemTheme key, its own Tests key, and its own icon handling. The vertical tab strip is a common request that Firefox does not provide natively, and reproducing it in userChrome CSS means restyling the tab strip container and making it behave like a sidebar, which is a substantial CSS job that the project has done. ## The cost of the approach, stated plainly The honest trade of a userChrome stylesheet is that you own the maintenance of an interface you do not control, and that is exactly what a project like this costs its users. Firefox changes its own chrome markup and class names regularly, and a stylesheet that targets them breaks when the underlying structure changes. That is why the project tracks Firefox releases so closely, with a Nova line for the current release and an ESR line for the long-lived branch, and why the Nova line moved from Firefox 140 to 158 while the ESR line moved from 140 to 153. Each Firefox version requires the stylesheet to be updated, and the version in the release name tells you which Firefox it targets. The second cost is the risk of a broken stylesheet. Because toolkit.legacyUserProfileCustomizations.stylesheets has to be enabled manually and the project is not distributed through an add-on that could validate the CSS before applying it, a mistake in a rule can produce an unusable browser window. The practical mitigation is to keep a copy of your profile, and to apply changes one at a time rather than replacing the whole chrome folder. The third cost is the about:config workflow itself. Every option is a preference name typed by hand, and the README lists dozens of them. That is more work than a settings dialog, and it is the price of the theme not shipping a UI. The upside is that the configuration is greppable, scriptable, and versionable, and that the whole behaviour set is documented in one file. ## Conclusion Adopt WaveFox if you want a Firefox that looks and behaves the way you set up, and if you are willing to edit CSS and about:config rather than pick from a theme gallery. Do not adopt it if you want a one-click theme or if you need to stay on the current Firefox release, since the Nova line requires the newest Firefox. Verify first which of the two lines you need, because the ESR branch is a different feature set with different keys. ## FAQ ### How do I install WaveFox Nova for Firefox? Download the chrome folder and put it in your user profile folder, then go to about:config and activate toolkit.legacyUserProfileCustomizations.stylesheets and browser.nova.enabled. The Nova line requires Firefox 158 on Windows, macOS, or Linux, while the ESR line requires Firefox 153 ESR and only needs the first key. ### Does WaveFox have a settings interface? No. Every option is an about:config preference named with a WaveFox prefix, such as WaveFox.HorizontalTabs.AttachedTabs, WaveFox.Toolbar.Roundings, and WaveFox.Icons. The README documents the key names and their accepted values. ### What is the difference between the WaveFox Nova and ESR lines? They are separate maintained lines with different feature sets, not one theme with two version numbers. Nova requires Firefox 158 and adds options for tests, tab shape modes, and cross-platform system themes, while the ESR line targets Firefox 153 ESR with a smaller set of keys and platform-specific transparency options. ### Which icons does WaveFox use? The icon set is third-party code, from firefox-csshacks or Lepton, and the author states the code will be updated according to the original source. The WaveFox.Icons key selects between the two options and requires the svg.context-properties.content.enabled key to be active. ### How do I enable transparency on Linux and Windows with WaveFox? On Windows 10, install DWMBlurGlass, then set WaveFox.Windows10.Transparency.Enabled and browser.tabs.inTitlebar to a value above 1. On Linux, set WaveFox.Linux.Transparency.Enabled with the same browser.tabs.inTitlebar requirement, plus WaveFox.Linux.Transparency.TextColor.White.Enabled. Both require an OS with transparency support and work only with the system theme. ## Sources - [Issues](https://github.com/QNetITQ/WaveFox/issues) - [License: MIT](https://github.com/QNetITQ/WaveFox/blob/main/LICENSE) - [QNetITQ/WaveFox on GitHub](https://github.com/QNetITQ/WaveFox) - [README](https://github.com/QNetITQ/WaveFox/blob/main/README.md) - [Releases](https://github.com/QNetITQ/WaveFox/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/qnetitq-wavefox