Configuration

Enable

To enable the Stylix module, declare:

{
  stylix.enable = true;
}

Color scheme

Handmade schemes

To set a Tinted Theming color scheme, declare:

{
  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.

Wallpaper

To set a wallpaper, provide a path or an arbitrary derivation:

• {
    stylix.image = ./wallpaper.png;
  }
  

• {
    stylix.image = pkgs.fetchurl {
      url = "https://www.pixelstalk.net/wp-content/uploads/2016/05/Epic-Anime-Awesome-Wallpapers.jpg";
      sha256 = "enQo3wqhgf0FEPHj2coOCvo7DuZv+x5rL/WIo4qPI50=";
    };
  }
  

If stylix.base16Scheme is undeclared, Stylix generates a color scheme based on the wallpaper using a genetic algorithm. Note that more colorful images tend to yield better results. The algorithm's polarity can be schewed towards a dark or light theme with:

• {
    stylix.polarity = "dark";
  }
  

• {
    stylix.polarity = "light";
  }
  

The generated color scheme can be viewed at /etc/stylix/palette.html on NixOS, or at ~/.config/stylix/palette.html on Home Manager.

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.

Standalone Nixvim

When using a NixOS or home-manager installation of Nixvim, you can use Stylix as normal. However, when using Nixvim's "standalone" configuration mode, you will need to pass Stylix's generated config to Nixvim yourself.

The generated config can be accessed as config.lib.stylix.nixvim.config. You can use this as a module in your standalone Nixvim Configuration or an extension of it.

For example:

{ inputs, config, pkgs, ... }:
let
  inherit (pkgs.stdenv.hostPlatform) system;
  nixvim-package = inputs.nixvim-config.packages.${system}.default;
  extended-nixvim = nixvim-package.extend config.lib.stylix.nixvim.config;
in
{
  environment.systemPackages = [
    extended-nixvim
  ];
}

Turning targets on and off

A target is anything which can have colors, fonts or a wallpaper applied to it.

You can discover the available targets and their options by browsing through the module reference at the end of this book. Most targets will be found under a module of the same name, but occasionally a module will serve multiple similar targets. For example, the Firefox module also provides options for other browsers which are based on Firefox.

For each target, there is an option like stylix.targets.«target».enable which you can use to turn its styling on or off. By default, it's turned on automatically whenever the target is installed. You can globally 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 themed.

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.