11.stylix/doc/src/configuration.md

# Configuration

## Enable

Stylix must be enabled before it will apply any changes to your system:

```nix
{
  stylix.enable = true;
}
```

## Color scheme

### Handmade schemes

To set a [Tinted Theming](https://github.com/tinted-theming/schemes) color
scheme, declare:

```nix
{ pkgs, ... }:
{
  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.

## Wallpaper

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

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

- ```nix
  { pkgs, ... }:
  {
    stylix.image = pkgs.fetchurl {
      url = "https://getwallpapers.com/wallpaper/full/1/4/3/523784.jpg";
      hash = "sha256-S/6kgloXiIYI0NblT6YVXfqELApbdHGsuYe6S4JoQwQ=";
    };
  }
  ```

If `stylix.base16Scheme` is undeclared, Stylix generates a color scheme based on
the wallpaper using a [genetic
algorithm](https://en.wikipedia.org/wiki/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:

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

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

Fonts can apply in three ways:

1. An app's own font options
  (e.g. [the Alacritty module](./options/modules/alacritty.html) sets home-manager's
  `programs.alacritty.settings.font`).

2. Widely, through
  [the Fontconfig module](./options/modules/fontconfig.html).

3. Made available in an environment using
  [the font packages module](./options/modules/font-packages.html).

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-color-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
{ config, ... }:
{
  stylix.fonts.serif = config.stylix.fonts.sansSerif;
}
```

Or even choose monospace for everything:

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

> [!NOTE]
>
> There is a special case involving the
> [`stylix.base16Scheme`](options/platforms/home_manager.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/platforms/home_manager.md#stylixoverride) is not inherited
> if the color scheme is different.

## 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](options/modules/firefox.md) 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.