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

GNOME 44

EnvironmentWallpaperColour schemeFontsFull configuration
GNOME 44Atlantis Garbage Worker by Grady FrederickGenerated by StylixCantarell, Fira CodeSee here

KDE Plasma 5

EnvironmentWallpaperColour schemeFontsFull configuration
KDE Plasma 5Taken from Genshin ImpactGenerated by StylixCantarell, Fira CodeSee here

Hyprland

EnvironmentWallpaperColour schemeFontsFull configuration
HyprlandTaken from raison d'etre by EveGenerated by StylixDeJavuSee 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.

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:

ScopePurpose
ciChanges to GitHub Actions workflows.
docChanges to the website, README.md, and so on.
stylixChanges in the stylix directory, flake.nix, and other global code.
Name of targetChanges to code for a particular target.
treewideChanges 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.

GDM login screen with a dark background color and showing a guest user

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.

Appearance tab in GNOME settings

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.

Toggles in GNOME quick settings

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.

Sidebar of Nautilus file manager

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

Recolored systemd logo

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.