configuration.md

# Configuration

## Enable

To enable the Stylix module, declare:

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

```nix
{
  stylix.image = ./wallpaper.png;
}
```

The option accepts derivations as well as paths, so you can fetch an image
directly from the internet:

```nix
{
  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](https://en.wikipedia.org/wiki/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:

```nix
{
  stylix.polarity = "dark";
}
```

The current scheme can be previewed in a web browser at either
[`/etc/stylix/palette.html`](file:///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](https://github.com/tinted-theming/schemes):

```nix
{
  stylix.base16Scheme = "${pkgs.base16-schemes}/share/themes/gruvbox-dark-hard.yaml";
}
```

This option also accepts other files and formats supported by
[`mkSchemeAttrs`](https://github.com/SenchoPens/base16.nix/blob/main/DOCUMENTATION.md#mkschemeattrs).

### Overriding

For convenience, it is possible to override parts of `stylix.base16Scheme` using
`stylix.override`. Anything that
[base16.nix](https://github.com/SenchoPens/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.

```nix
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](https://github.com/SenchoPens/base16.nix/blob/main/DOCUMENTATION.md#mkschemeattrs)
for more info.

For more complex configurations you may find it simpler to use
[mustache](http://mustache.github.io/) templates to generate output files.
See [base16.nix](https://github.com/SenchoPens/base16.nix) documentation for
usage examples.

## Fonts

The default combination of fonts is:

```nix
{
  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:

```nix
{
  stylix.fonts.serif = config.stylix.fonts.sansSerif;
}
```

Or even choose monospace for everything:

```nix
{
  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`](options/nixos.md#stylixhomemanagerintegrationautoimport)
and
[`stylix.homeManagerIntegration.followSystem`](options/nixos.md#stylixhomemanagerintegrationfollowsystem)
to customize this.

> [!NOTE]
>
> There is a special case involving the
> [`stylix.base16Scheme`](options/nixos.md#stylixbase16scheme)
> 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`](options/nixos.md#stylixoverride) 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](options/nixos.md) and
[Home Manager](options/hm.md) respectively.