Skip to main content

Flavors (BETA)

The "flavor" is a pre-made Yazi theme, while what we typically refer to as a "theme" is the user's own theme, i.e. ~/.config/yazi/theme.toml file.

The purpose of separating them is to allow users to customize their preferences more conveniently on top of an existing flavor, without having to modify those flavor files. This makes it easier to update, as there won't be conflicts when pulling from Git.

Behind the scenes, Yazi merges the user's theme.toml with the flavor's flavor.toml automatically, and the user's always takes precedence over the flavor.

Directory structure​

These flavors are placed in the flavors subdirectory of the Yazi configuration directory, so either:

  • ~/.config/yazi/flavors/ on Unix-like systems.
  • C:\Users\USERNAME\AppData\Roaming\yazi\config\flavors\ on Windows.
~/.config/yazi/
├── flavors/
│   ├── foo.yazi/
│   └── bar.yazi/
└── theme.toml

Each flavor is a directory with a kebab-case name, ending in .yazi, and containing at least the following files:

~/.config/yazi/flavors/bar.yazi/
├── flavor.toml
├── tmtheme.xml
├── README.md
├── preview.png
├── LICENSE
└── LICENSE-tmtheme

Where:

  • flavor.toml is this flavor's configuration file, in the format consistent with the user's theme.toml.
  • tmtheme.xml is a tmTheme file that matches the colors of this flavor for code highlighting.
  • README.md and preview.png are the description and the preview image of this flavor, respectively.
  • LICENSE and LICENSE-tmtheme are the licenses for the flavor and the tmtheme.xml file, respectively.

Usage​

For example, if you want to use the bar.yazi flavor in dark mode, set the content of your theme.toml to:

[flavor]
dark = "bar"

or use it in light mode:

[flavor]
light = "bar"

If you want to use the bar.yazi flavor in both dark and light modes:

[flavor]
dark  = "bar"
light = "bar"

Make sure your theme.toml doesn't contain anything other than [flavor], unless you want to override certain styles of the bar.yazi flavor.

Why flavors over themes?​

We recommend using the new flavor format instead of the old theme, because flavors:

  • More powerful - auto dark/light mode switching with the terminal
  • Easier to update - can be managed with the ya pack package manager
  • Offers configuration merging - override some styles from flavor.toml in your own theme.toml

Cooking a flavor​

Please use our flavor-template repository as a starting point to create your own flavor.