Stylix
Stylix is a NixOS module which applies the same colour scheme, font and wallpaper to a range of applications and desktop environments.
What's this?
base16.nix allows you to import colours from base16 into Nix code. Stylix takes this a step further:
- Automatically colours and changes the font of apps
- Sets your wallpaper
- Exports the colour scheme to be used manually for anything we missed
- Can also generate themes based on an image
For those not familiar with NixOS and Home Manager:
- NixOS is a Linux distribution
- Home Manager is a program which runs anywhere
- Both use the Nix language and package manager
- Both let you install programs and change settings via code
Stylix supports either NixOS + Home Manager, or Home Manager on its own. Certain features are only available with NixOS.
Resources
Please refer to the Stylix book for instructions and a list of supported apps.
If you have any questions, you are welcome to join our Matrix room, or ask on GitHub Discussions.
Example configurations
Environment | Wallpaper | Colour scheme | Fonts | Full configuration |
---|---|---|---|---|
GNOME 44 | Atlantis Garbage Worker by Grady Frederick | Generated by Stylix | Cantarell, Fira Code | See here |
Environment | Wallpaper | Colour scheme | Fonts | Full configuration |
---|---|---|---|---|
KDE Plasma 5 | Taken from Genshin Impact | Generated by Stylix | Cantarell, Fira Code | See here |
Environment | Wallpaper | Colour scheme | Fonts | Full configuration |
---|---|---|---|---|
Hyprland | Taken from raison d'etre by Eve | Generated by Stylix | DeJavu | See here |
Installation
NixOS
You can install Stylix into your NixOS configuration using Flakes. This will provide theming for system level programs such as bootloaders, splash screens, and display managers.
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
stylix.url = "github:danth/stylix";
};
outputs = { nixpkgs, stylix, ... }: {
nixosConfigurations."«hostname»" = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [ stylix.nixosModules.stylix ./configuration.nix ];
};
};
}
Minimal flake.nix
for a NixOS configuration.
Many applications cannot be configured system wide, so Stylix will also need Home Manager to be able to change their settings within your home directory.
Installing Home Manager as a NixOS module is highly recommended if you don't use it already. This will combine it with your existing configuration, so you don't need to run any extra commands when you rebuild, and the theme you set in NixOS will automatically be used for Home Manager too.
When Stylix is installed to a NixOS configuration, it will automatically set up its Home Manager modules if it detects that Home Manager is available. You can theoretically use it without installing Home Manager, however most features will be unavailable.
nix-darwin
You can install Stylix into your nix-darwin configuration in a similar fashion to NixOS via Flakes.
{
inputs = {
darwin = {
url = "github:LnL7/nix-darwin";
inputs.nixpkgs.follows = "nixpkgs";
};
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
stylix.url = "github:danth/stylix";
};
outputs = { darwin, nixpkgs, stylix, ... }: {
darwinConfigurations."«hostname»" = darwin.lib.darwinSystem {
system = "aarch64-darwin";
modules = [ stylix.darwinModules.stylix ./configuration.nix ];
};
};
}
Minimal flake.nix
for a nix-darwin configuration.
While this won't have an effect on the looks of MacOS, since we don't have the controls to theme it like we do NixOS, it will automatically set up the Home Manager modules for you.
Home Manager
If you would prefer to use the standalone version of Home Manager, you can install Stylix directly into your Home Manager configuration instead. This could be useful if you are on another operating system, or a machine which is managed by someone else.
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
home-manager.url = "github:nix-community/home-manager";
stylix.url = "github:danth/stylix";
};
outputs = { nixpkgs, home-manager, stylix, ... }: {
homeConfigurations."«username»" = home-manager.lib.homeManagerConfiguration {
pkgs = nixpkgs.legacyPackages.x86_64-linux;
modules = [ stylix.homeManagerModules.stylix ./home.nix ];
};
};
}
Minimal flake.nix
for a Home Manager configuration.
If you choose to use both NixOS and Home Manager but configure them separately, you will need to copy the settings described below into both of your configurations, as keeping them separate means that they cannot follow each other automatically.
Without flakes
If you haven't enabled flakes yet or don't want to use this feature, default.nix
re-exports all the flake outputs, without requiring flakes to be enabled. This means
that once you have a copy of this repo, using either a local checkout,
niv, or any other method, you can import it to
get the NixOS module as the nixosModules.stylix
attribute and the Home Manager
module as the homeManagerModules.stylix
attribute.
let
stylix = pkgs.fetchFromGitHub {
owner = "danth";
repo = "stylix";
rev = "...";
sha256 = "...";
};
in {
imports = [ (import stylix).homeManagerModules.stylix ];
stylix.image = ./wallpaper.jpg;
}
Example usage of the Home Manager module without flakes.
Configuration
Wallpaper
To start theming, you need to set a wallpaper image.
{
stylix.image = ./wallpaper.png;
}
The option accepts derivations as well as paths, so you can fetch an image directly from the internet:
{
stylix.image = pkgs.fetchurl {
url = "https://www.pixelstalk.net/wp-content/uploads/2016/05/Epic-Anime-Awesome-Wallpapers.jpg";
sha256 = "enQo3wqhgf0FEPHj2coOCvo7DuZv+x5rL/WIo4qPI50=";
};
}
Color scheme
Generated schemes
If you only set a wallpaper, Stylix will use a genetic algorithm to create a color scheme. The quality of these schemes can vary, but more colorful images tend to have better results.
You can force a light or dark scheme using the polarity option:
{
stylix.polarity = "dark";
}
The current scheme can be previewed in a web browser at either
/etc/stylix/palette.html
for NixOS, or
~/.config/stylix/palette.html
for Home Manager.
Handmade schemes
If you prefer a handmade color scheme, you can choose anything from the Tinted Theming repository:
{
stylix.base16Scheme = "${pkgs.base16-schemes}/share/themes/gruvbox-dark-hard.yaml";
}
This option also accepts other files and formats supported by
mkSchemeAttrs
.
Overriding
For convenience, it is possible to override parts of stylix.base16Scheme
using
stylix.override
. Anything that
base16.nix accepts as override is
valid.
When using both the Home Manager and NixOS modules, both the system overrides
and the user-provided one are used in the user configuration if
stylix.base16Scheme
is not changed in the user config. If that is the case,
only the user override is used.
Fonts
The default combination of fonts is:
{
stylix.fonts = {
serif = {
package = pkgs.dejavu_fonts;
name = "DejaVu Serif";
};
sansSerif = {
package = pkgs.dejavu_fonts;
name = "DejaVu Sans";
};
monospace = {
package = pkgs.dejavu_fonts;
name = "DejaVu Sans Mono";
};
emoji = {
package = pkgs.noto-fonts-emoji;
name = "Noto Color Emoji";
};
};
}
These can be changed as you like.
To make things look more uniform, you could replace the serif font with the sans-serif font:
{
stylix.fonts.serif = config.stylix.fonts.sansSerif;
}
Or even choose monospace for everything:
{
stylix.fonts = {
serif = config.stylix.fonts.monospace;
sansSerif = config.stylix.fonts.monospace;
emoji = config.stylix.fonts.monospace;
};
}
Multi-user configurations
For those apps which are configured through Home Manager, Stylix allows you to choose a different theme for each user. This can be done by setting the theme within Home Manager for that user rather than at the system level.
By default, all users follow the system theme. This can be turned off by
setting stylix.homeManagerIntegration.followSystem = false
, in which case you
must explicitly set a theme for each user. Setting that option is not required
just to be able to override an individual theme.
If you would like to disable all Home Manager activity for a user, you can set
stylix.homeManagerIntegration.autoImport = false
, then manually import the
Home Manager module for the users for which it should be enabled.
Note that if the wallpaper image for a user is different to the rest of the
system, a separate theme will always be generated for them, even though their
base16Scheme
option has not been overridden. If you want that user to follow
the system theme while having a different wallpaper, you will need to manually
copy the system theme into their configuration. (This behaviour is necessary as
otherwise it would be impossible to use a generated theme for a user while
having a manually created theme for the rest of the system.)
Turning targets on and off
In Stylix terms, a target is anything which can have colors, fonts or a wallpaper applied to it. Each module in this repository should correspond to a target of the same name.
Each target has an option like stylix.targets.«target».enable
to turn its
styling on or off. Normally, it's turned on automatically when the target is
installed. You can set stylix.autoEnable = false
to opt out of this
behaviour, in which case you'll need to manually enable each target you want to
be styled.
Targets are different between Home Manager and NixOS, and sometimes available in both cases. If both are available, it is always correct to enable both. The reference pages have a list of targets for NixOS and Home Manager respectively.
Tips and tricks
Adjusting the brightness and contrast of a background image
If you want to use a background image for your desktop but find it too bright or distracting, you can use the imagemagick
package to dim the image, or adjust its brightness and contrast to suit your preference.
Here's an example Nix expression that takes an input image, applies a brightness/contrast adjustment to it, and saves the result as a new image file:
{ pkgs, ... }:
let
inputImage = ./path/to/image.jpg;
brightness = -30;
contrast = 0;
fillColor = "black"
in
{
stylix.image = pkgs.runCommand "dimmed-background.png" { } ''
${pkgs.imagemagick}/bin/convert "${inputImage}" -brightness-contrast ${brightness},${contrast} -fill ${fillColor} $out
'';
}
Dynamic wallpaper generation based on selected theme
With imagemagick, you can also dynamically generate wallpapers based on the selected theme. Similarly, you can use a template image and repaint it for the current theme.
{ pkgs, ... }:
let
theme = "${pkgs.base16-schemes}/share/themes/catppuccin-latte.yaml";
wallpaper = pkgs.runCommand "image.png" {} ''
COLOR=$(${pkgs.yq}/bin/yq -r .base00 ${theme})
COLOR="#"$COLOR
${pkgs.imagemagick}/bin/magick convert -size 1920x1080 xc:$COLOR $out
'';
in {
stylix = {
image = wallpaper;
base16Scheme = theme;
};
}
Which is neatly implemented as a single function in lib.stylix.pixel
:
{ pkgs, config, ... }:
{
stylix = {
image = config.lib.stylix.pixel "base0A";
base16Scheme = "${pkgs.base16-schemes}/share/themes/catppuccin-latte.yaml";
};
}
NixOS options
The following options can only be set in a NixOS configuration.
stylix.autoEnable
Whether to automatically enable styling for installed targets.
Type: boolean
Default:
true
stylix.base16Scheme
A scheme following the base16 standard.
This can be a path to a file, a string of YAML, or an attribute set.
Type: path or strings concatenated with “\n” or (attribute set)
Default: The colors used in the theming.
Those are automatically selected from the background image by default, but could be overridden manually.
stylix.cursor.package
Package providing the cursor theme.
Type: package
Default:
<derivation vanilla-dmz-0.4.5>
stylix.cursor.name
The cursor name within the package.
Type: string
Default:
"Vanilla-DMZ"
stylix.cursor.size
The cursor size.
Type: signed integer
Default:
32
stylix.fonts.packages
A list of all the font packages that will be installed.
Type: list of package (read only)
stylix.fonts.emoji
Emoji font.
Type: submodule
Default:
{
name = "Noto Color Emoji";
package = <derivation noto-fonts-color-emoji-2.042>;
}
stylix.fonts.emoji.package
Package providing the font.
Type: package
stylix.fonts.emoji.name
Name of the font within the package.
Type: string
stylix.fonts.monospace
Monospace font.
Type: submodule
Default:
{
name = "DejaVu Sans Mono";
package = <derivation dejavu-fonts-2.37>;
}
stylix.fonts.monospace.package
Package providing the font.
Type: package
stylix.fonts.monospace.name
Name of the font within the package.
Type: string
stylix.fonts.sansSerif
Sans-serif font.
Type: submodule
Default:
{
name = "DejaVu Sans";
package = <derivation dejavu-fonts-2.37>;
}
stylix.fonts.sansSerif.package
Package providing the font.
Type: package
stylix.fonts.sansSerif.name
Name of the font within the package.
Type: string
stylix.fonts.serif
Serif font.
Type: submodule
Default:
{
name = "DejaVu Serif";
package = <derivation dejavu-fonts-2.37>;
}
stylix.fonts.serif.package
Package providing the font.
Type: package
stylix.fonts.serif.name
Name of the font within the package.
Type: string
stylix.fonts.sizes.applications
The font size used by applications.
Type: unsigned integer, meaning >=0
Default:
12
stylix.fonts.sizes.desktop
The font size used in window titles/bars/widgets elements of the desktop.
Type: unsigned integer, meaning >=0
Default:
10
stylix.fonts.sizes.popups
The font size for notifications/popups and in general overlay elements of the desktop.
Type: unsigned integer, meaning >=0
Default:
10
stylix.fonts.sizes.terminal
The font size for terminals/text editors.
Type: unsigned integer, meaning >=0
Default:
12
stylix.homeManagerIntegration.autoImport
Whether to enable Stylix automatically for every user.
This only applies to users for which Home Manager is set up within the NixOS configuration.
Type: boolean
Default:
true
when Home Manager is present.
stylix.homeManagerIntegration.followSystem
When this option is true
, Home Manager will follow
the system theme by default, rather than requiring a theme to be set.
This will only affect Home Manager configurations which are built within the NixOS configuration.
Type: boolean
Default:
true
stylix.image
Wallpaper image.
This is set as the background of your desktop environment, if possible, and used to generate a colour scheme if you don’t set one manually.
Type: path or package convertible to it
Default:
null
stylix.opacity.applications
The opacity of the windows of applications, the amount of applications supported is currently limited
Type: floating point number
Default:
1.0
stylix.opacity.desktop
The opacity of the windows of bars/widgets, the amount of applications supported is currently limited
Type: floating point number
Default:
1.0
stylix.opacity.popups
The opacity of the windows of notifications/popups, the amount of applications supported is currently limited
Type: floating point number
Default:
1.0
stylix.opacity.terminal
The opacity of the windows of terminals, this works across all terminals supported by stylix
Type: floating point number
Default:
1.0
stylix.override
An override that will be applied to stylix.base16Scheme when generating lib.stylix.colors.
Takes anything that a scheme generated by base16nix can take as argument to override.
Type: attribute set
Default:
{ }
stylix.polarity
Use this option to force a light or dark theme.
By default we will select whichever is ranked better by the genetic algorithm. This aims to get good contrast between the foreground and background, as well as some variety in the highlight colours.
Type: one of “either”, “light”, “dark”
Default:
"either"
stylix.targets.chromium.enable
Whether to style Chromium, Google Chrome and Brave.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.console.enable
Whether to style the Linux kernel console.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.feh.enable
Whether to style the desktop background using Feh.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.fish.enable
Whether to style Fish.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.gnome.enable
Whether to style GNOME and GDM
Type: boolean
Default:
false
stylix.targets.grub.enable
Whether to style GRUB.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.grub.useImage
Whether to use your wallpaper image as the GRUB background.
Type: boolean
Default:
false
stylix.targets.gtk.enable
Whether to style all GTK3, GTK4 and Libadwaita apps.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.kmscon.enable
Whether to style the kmscon virtual console.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.lightdm.enable
Whether to style LightDM.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.nixos-icons.enable
Whether to style the NixOS logo.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.nixvim.enable
Whether to style nixvim.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.nixvim.transparent_bg.main
Whether to enable background transparency for the main NeoVim window.
Type: boolean
Default:
false
Example:
true
stylix.targets.nixvim.transparent_bg.sign_column
Whether to enable background transparency for the NeoVim sign column.
Type: boolean
Default:
false
Example:
true
stylix.targets.plymouth.enable
Whether to style the Plymouth boot screen.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.plymouth.logo
Logo to be used on the boot screen.
Type: path or package
Default: NixOS logo
stylix.targets.plymouth.logoAnimated
Whether to apply a spinning animation to the logo.
Disabling this allows the use of logos which don’t have rotational symmetry.
Type: boolean
Default:
true
Home Manager options
The following options can only be set in a Home Manager configuration.
If you combined Home Manager with your NixOS configuration, write these options within a Home Manager section, either for all users:
home-manager.sharedModules = [{
stylix.targets.xyz.enable = false;
}];
Or for a specific user:
home-manager.users.«name» = {
stylix.targets.xyz.enable = false;
};
Read more about per-user themes.
stylix.autoEnable
Whether to automatically enable styling for installed targets.
Type: boolean
Default:
true
stylix.base16Scheme
A scheme following the base16 standard.
This can be a path to a file, a string of YAML, or an attribute set.
Type: path or strings concatenated with “\n” or (attribute set)
Default: The colors used in the theming.
Those are automatically selected from the background image by default, but could be overridden manually.
stylix.cursor.package
Package providing the cursor theme.
Type: package
Default:
<derivation vanilla-dmz-0.4.5>
stylix.cursor.name
The cursor name within the package.
Type: string
Default:
"Vanilla-DMZ"
stylix.cursor.size
The cursor size.
Type: signed integer
Default:
32
stylix.fonts.packages
A list of all the font packages that will be installed.
Type: list of package (read only)
stylix.fonts.emoji
Emoji font.
Type: submodule
Default:
{
name = "Noto Color Emoji";
package = <derivation noto-fonts-color-emoji-2.042>;
}
stylix.fonts.emoji.package
Package providing the font.
Type: package
stylix.fonts.emoji.name
Name of the font within the package.
Type: string
stylix.fonts.monospace
Monospace font.
Type: submodule
Default:
{
name = "DejaVu Sans Mono";
package = <derivation dejavu-fonts-2.37>;
}
stylix.fonts.monospace.package
Package providing the font.
Type: package
stylix.fonts.monospace.name
Name of the font within the package.
Type: string
stylix.fonts.sansSerif
Sans-serif font.
Type: submodule
Default:
{
name = "DejaVu Sans";
package = <derivation dejavu-fonts-2.37>;
}
stylix.fonts.sansSerif.package
Package providing the font.
Type: package
stylix.fonts.sansSerif.name
Name of the font within the package.
Type: string
stylix.fonts.serif
Serif font.
Type: submodule
Default:
{
name = "DejaVu Serif";
package = <derivation dejavu-fonts-2.37>;
}
stylix.fonts.serif.package
Package providing the font.
Type: package
stylix.fonts.serif.name
Name of the font within the package.
Type: string
stylix.fonts.sizes.applications
The font size used by applications.
Type: unsigned integer, meaning >=0
Default:
12
stylix.fonts.sizes.desktop
The font size used in window titles/bars/widgets elements of the desktop.
Type: unsigned integer, meaning >=0
Default:
10
stylix.fonts.sizes.popups
The font size for notifications/popups and in general overlay elements of the desktop.
Type: unsigned integer, meaning >=0
Default:
10
stylix.fonts.sizes.terminal
The font size for terminals/text editors.
Type: unsigned integer, meaning >=0
Default:
12
stylix.image
Wallpaper image.
This is set as the background of your desktop environment, if possible, and used to generate a colour scheme if you don’t set one manually.
Type: path or package convertible to it
Default:
null
stylix.opacity.applications
The opacity of the windows of applications, the amount of applications supported is currently limited
Type: floating point number
Default:
1.0
stylix.opacity.desktop
The opacity of the windows of bars/widgets, the amount of applications supported is currently limited
Type: floating point number
Default:
1.0
stylix.opacity.popups
The opacity of the windows of notifications/popups, the amount of applications supported is currently limited
Type: floating point number
Default:
1.0
stylix.opacity.terminal
The opacity of the windows of terminals, this works across all terminals supported by stylix
Type: floating point number
Default:
1.0
stylix.override
An override that will be applied to stylix.base16Scheme when generating lib.stylix.colors.
Takes anything that a scheme generated by base16nix can take as argument to override.
Type: attribute set
Default:
{ }
stylix.polarity
Use this option to force a light or dark theme.
By default we will select whichever is ranked better by the genetic algorithm. This aims to get good contrast between the foreground and background, as well as some variety in the highlight colours.
Type: one of “either”, “light”, “dark”
Default:
"either"
stylix.targets.alacritty.enable
Whether to style Alacritty.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.avizo.enable
Whether to style Avizo.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.bat.enable
Whether to style Bat.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.bemenu.enable
Whether to style bemenu.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.bemenu.alternate
Whether to use alternating colours.
Type: boolean
Default:
false
stylix.targets.bemenu.fontSize
Font size used for bemenu.
Type: null or signed integer
Default:
10
stylix.targets.bspwm.enable
Whether to style bspwm.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.btop.enable
Whether to style btop.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.dunst.enable
Whether to style Dunst.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.emacs.enable
Whether to style Emacs.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.feh.enable
Whether to style the desktop background using Feh.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.firefox.enable
Whether to style Firefox.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.firefox.profileNames
The Firefox profile names to apply styling on.
Type: list of string
Default:
[ ]
stylix.targets.fish.enable
Whether to style Fish.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.foot.enable
Whether to style Foot.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.fuzzel.enable
Whether to style Fuzzel.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.fzf.enable
Whether to style Fzf.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.gedit.enable
Whether to style GEdit.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.gnome.enable
Whether to style GNOME.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.gtk.enable
Whether to style all GTK3, GTK4 and Libadwaita apps.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.gtk.extraCss
Extra code added to gtk-3.0/gtk.css
and gtk-4.0/gtk.css
.
Type: strings concatenated with “\n”
Default:
""
Example:
''
// Remove rounded corners
window.background { border-radius: 0; }
''
stylix.targets.helix.enable
Whether to style Helix.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.hyprland.enable
Whether to style Hyprland.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.i3.enable
Whether to style i3.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.k9s.enable
Whether to style k9s.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.kde.enable
Whether to style KDE.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.kitty.enable
Whether to style Kitty.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.kitty.variant256Colors
Whether to use the 256-color variant rather than the default combination of colors.
Type: boolean
Default:
false
stylix.targets.lazygit.enable
Whether to style lazygit.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.mako.enable
Whether to style Mako.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.mangohud.enable
Whether to style mangohud.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.nixvim.enable
Whether to style nixvim.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.nixvim.transparent_bg.main
Whether to enable background transparency for the main NeoVim window.
Type: boolean
Default:
false
Example:
true
stylix.targets.nixvim.transparent_bg.sign_column
Whether to enable background transparency for the NeoVim sign column.
Type: boolean
Default:
false
Example:
true
stylix.targets.nushell.enable
Whether to style Nushell.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.qutebrowser.enable
Whether to style Qutebrowser.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.rofi.enable
Whether to style Rofi.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.sway.enable
Whether to style Sway.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.swaylock.enable
Whether to style Swaylock.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.swaylock.useImage
Whether to use your wallpaper image for the Swaylock background. If this is disabled, a plain color will be used instead.
Type: boolean
Default:
true
stylix.targets.sxiv.enable
Whether to style Sxiv.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.tmux.enable
Whether to style Tmux.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.vim.enable
Whether to style Vim and/or Neovim.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.vscode.enable
Whether to style VSCode.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.waybar.enable
Whether to style Waybar.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.waybar.enableCenterBackColors
enables background colors on the center of the bar
Type: boolean
Default:
false
stylix.targets.waybar.enableLeftBackColors
enables background colors on the left side of the bar
Type: boolean
Default:
false
stylix.targets.waybar.enableRightBackColors
enables background colors on the right side of the bar
Type: boolean
Default:
false
stylix.targets.wezterm.enable
Whether to style wezterm.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.xfce.enable
Whether to style Xfce.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.xresources.enable
Whether to style Xresources.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.yazi.enable
Whether to style Yazi.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.zathura.enable
Whether to style Zathura.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
stylix.targets.zellij.enable
Whether to style zellij.
Type: boolean
Default:
true
if stylix.autoEnable == true
and the target is installed,
otherwise false
.
Contributing to Stylix
Commit messages
To keep things consistent, commit messages should follow a format similar to Nixpkgs:
«scope»: «summary»
«motivation for change»
Where the scope is one of:
Scope | Purpose |
---|---|
ci | Changes to GitHub Actions workflows. |
doc | Changes to the website, README.md , and so on. |
stylix | Changes in the stylix directory, flake.nix , and other global code. |
Name of target | Changes to code for a particular target. |
treewide | Changes across many targets. |
The scope is meant to indicate which area of the code was changed. Specifying
the type of change, such as feat
or fix
, is not necessary. Dependency
updates should use whichever scope they are related to.
The summary should start with a lowercase letter, and should not end with punctuation.
Most commits to master
will also include a pull request number in brackets
after the summary. GitHub adds this automatically when creating a squash merge.
Old commits
Commits before 2024 did not follow any particular format. Some have emojis from GitMoji.
Adding modules
Development setup
Currently the easiest way to test Stylix is to use the new code in your actual configuration.
You might find it useful to change the flake reference in your configuration
from github:danth/stylix
to git+file:/home/user/path/to/stylix
so that you don't need to push your changes to GitHub during testing.
Then, remember to run nix flake lock --update-input stylix
to refresh the
flake each time you make an edit.
Nix only reads files which are tracked by Git, so you also need to
git add «file»
after creating a new file.
Module naming
Modules should be named like modules/«name»/«platform».nix
. For example,
modules/avizo/hm.nix
is a Home Manager module which themes Avizo.
The following platforms are supported:
- NixOS (
nixos
) - Home Manager (
hm
) - Nix-Darwin (
darwin
)
Correctly named modules will be imported automatically.
Other files needed by the module can also be stored within the
modules/«name»
folder, using any name which is not on the list above.
Module template
All modules should have an enable option created using mkEnableTarget
.
This is similar to
mkEnableOption
from the standard library, however it integrates with
stylix.autoEnable
and generates more specific documentation.
A general format for modules is shown below.
{ config, lib, ... }:
{
stylix.targets.«name».enable = config.lib.stylix.mkEnableTarget "«human readable name»";
config = lib.mkIf config.stylix.targets.«name».enable {
};
}
The human readable name must fit into the following sentence:
Whether to style «human readable name».
How to apply colors
Refer to the style guide to see how colors are named, and where to use each one.
The colors are exported under config.lib.stylix.colors
, which originates from
mkSchemeAttrs
.
You can use the values directly:
{
environment.variables.MY_APPLICATION_COLOR = config.lib.stylix.colors.base05;
}
Or you can create a Mustache template and use it as a function. This returns a derivation which builds the template.
{
environment.variables.MY_APPLICATION_CONFIG_FILE =
let configFile = config.lib.stylix.colors {
template = ./config.toml.mustache;
extension = ".toml";
};
in "${configFile}";
}
Setting options through an existing NixOS or Home Manager module is preferable to generating whole files, since users will have the option of overriding things individually.
Also note that reading generated files with builtins.readFile
can be very
slow and should be avoided.
How to apply other things
For everything else, like fonts and wallpapers, you can just take option values
directly from config
. See the reference pages for a list of options.
Testbeds
Stylix provides a suite of virtual machines which can be used to test and preview themes without installing the target to your live system.
These can be particularly helpful for:
- Working on targets before the login screen, since you can avoid closing your editor to see the result.
- Developing for a different desktop environment than the one you normally use.
- Reducing the risk of breaking your system while reviewing pull requests.
Testbeds are also built by GitHub Actions for every pull request. This is less beneficial compared to running them yourself, since it cannot visually check the theme, however it can catch build failures which may have been missed otherwise.
Creation
New testbeds are defined by creating a file called testbed.nix
within the
folder for the corresponding target. This file will automatically be loaded
as a NixOS module, with options such as stylix.image
already defined.
The module should include any options necessary to install the target and
any supporting software - for example, a window manager.
If the target can only be used through Home Manager, you can write a Home Manager module within the NixOS module using the following format:
{
home-manager.sharedModules = [{
# Write Home Manager options here
}];
}
Using home-manager.sharedModules
is preferred over home-manager.users.guest
since it allows us to easily change the username or add additional users in
the future.
Once the module is complete, use git add
to track the file, then the new
packages will be available to use.
Usage
You can list the available testbeds by running this command from anywhere within the repository:
user@host:~$ nix flake show
github:danth/stylix
└───packages
└───x86_64-linux
├───docs: package 'stylix-book'
├───palette-generator: package 'palette-generator'
├───testbed-gnome-dark: package 'testbed-gnome-dark'
├───testbed-gnome-light: package 'testbed-gnome-light'
├───testbed-kde-dark: package 'testbed-kde-dark'
└───testbed-kde-light: package 'testbed-kde-light'
(This has been edited down to only the relevant parts.)
To start a testbed, each of which is named in the format
testbed-«target»-«polarity»
, run the following command:
user@host:~$ nix run .#testbed-«target»-«polarity»
Any package with a name not fitting the given format is not a testbed, and may behave differently with this command, or not work at all.
Once the virtual machine starts, a window should open, similar to the screenshot below. The contents of the virtual machine will vary depending on the target you selected earlier.
If the testbed includes a login screen, the guest user should log in automatically when selected. Depending on the software used, you may still be presented with a password prompt - in which case you can leave it blank and proceed by pressing enter.
Style guide
The base16 style guide is generally targeted towards text editors. Stylix aims to support a variety of other applications, and as such it requires its own guide to keep colours consistent. Towards this goal we will define several common types of applications and how to style each of them using the available colours.
Please keep in mind that this is a general guide; there will be several applications that don't fit into any of the groups below. In this case it is up to the committer to make sure said application fits in stylistically with the rest of the themed applications.
It is also importent to note that this is a growing theming guide and when theming an application and you find the guide to be lacking in any way in terms of direction, you are encouraged to open an issue regarding what you would like to see added to the style guide.
Terms
Alternate
An alternate color should be used when something needs to look separate while not being drastically different. The smaller or less common element should use the alternate color.
For example, each section in this settings menu uses the alternate background color to separate it from the rest of the window, which is using the default background.
On/Off
This is for toggles or simple status indicators which have an obvious on and off state.
In the screenshot above the Wired and Night Light buttons are on, Power Mode is off.
Lists and selections
A list of items to select between, such as tabs in a web browser. The selection is the currently active item, or there could be multiple selected depending on the use case.
General colors
- Default background: base00
- Alternate background: base01
- Selection background: base02
- Default text: base05
- Alternate text: base04
- Warning: base0A
- Urgent: base09
- Error: base08
Window Managers
Window Managers arrange windows and provide decorations like title bars and borders. Examples include Sway and i3.
This does not include applications bundled with the desktop environment such as file managers, which would fall into the general category. Desktop helpers such as taskbars and menus are not technically part of the window manager, although they're often configured in the same place.
An urgent window is one which is grabbing for attention - Windows shows this by a flashing orange taskbar icon.
- Unfocused window border: base03
- Focused window border: base0A
- Unfocused window border in group: base0D
- Focused window border in group: base06
- Urgent window border: base07
- Window title text: base05
Notifications and Popups
Notifications and popups are any application overlay intended to be displayed over other applications. Examples include the mako notification daemon and avizo.
- Window border: base0D
- Low urgency background color: base06
- Low urgency text color: base0A
- High urgency background color: base0F
- High urgency text color: base08
- Incomplete part of progress bar: base01
- Complete part of progress bar: base02
Desktop Helpers
Applications that fall under this group are applications that complement the window management facilities of whatever window manager the user is using. Examples of this include waybar and polybar, as well as the similar programs that are part of KDE and GNOME.
Light text color widgets
Refer to general colors above.
Dark text color widgets
These widgets use a different text color than usual to ensure it's still readable when the background is more vibrant.
- Default text color: base00
- Alternate text color: base01
- Item on background color: base0E
- Item off background color: base0D
- Alternate item on background color: base09
- Alternate item off background color: base02
- List unselected background: base0D
- List selected background: base03
Images
For creating modified versions of logos, icons, etc; where we would rather the colors be similar to the original.
Note that the colors provided by the scheme won't necessarily match the names given below, although most handmade schemes do.
- Background color: base00
- Alternate background color: base01
- Main color: base05
- Alternate main color: base04
- Red: base08
- Orange: base09
- Yellow: base0A
- Green: base0B
- Cyan: base0C
- Blue: base0D
- Purple: base0E
- Brown: base0F
Example of a modified systemd logo. The square brackets are using the main color, which is usually be white or black depending on the polarity of the scheme.
Text Editors/Viewers
Text editors are any application that can view or edit source code. Examples include vim, helix, and bat.
For these please refer to the official base16 style guide.