Configuration

Enable

To enable the Stylix module, declare:

{
  stylix.enable = true;
}

Note

The global enable option was recently added, so you may come across old examples which don't include it. No other settings will take effect unless stylix.enable is set to true.

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.

Extending

When passing colors to unsupported targets or creating custom modules, it is possible to access values from the configured color scheme through config.lib.stylix.colors. An overview of the available values is shown below.

config.lib.stylix.colors = {
  base08 = "ff0000";
  base08-hex-r = "ff";
  base08-dec-r = "0.996094";
  # ...
  red = "ff0000";
  # ...
  withHashtag = {
    base08 = "#ff0000";
    # ...
  };
};

This attrset is generated by mkSchemeAttrs from base16.nix. Refer to the documentation for more info.

For more complex configurations you may find it simpler to use mustache templates to generate output files. See base16.nix documentation for usage examples.

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;
  };
}

Home Manager inheritance

By default, if Home Manager is used as part of NixOS, then Stylix will be automatically installed for all users, and the NixOS theme will become their default settings.

This is convenient for single-user systems, since you can configure everything once at the system level and it will automatically carry over. For multi-user systems, you can override the settings within Home Manager to select a different theme for each user.

You may prefer to disable inheritance entirely, and set up the Home Manager version of Stylix yourself if required. Refer to the options stylix.homeManagerIntegration.autoImport and stylix.homeManagerIntegration.followSystem to customize this.

Note

There is a special case involving the stylix.base16Scheme option:

If the wallpaper in a Home Manager configuration is changed, then Home Manager will stop inheriting the color scheme from NixOS. This allows Home Manager configurations to use the automatic palette generator without being overridden.

Similarly, stylix.override is not inherited if the color scheme is different.

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.