> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sxyazi/yazi/llms.txt
> Use this file to discover all available pages before exploring further.

# theme.toml

> Customize Yazi's colors, styles, and visual appearance

The `theme.toml` file controls Yazi's visual appearance including colors, text styles, and icons.

## File Location

* **Unix-like systems**: `~/.config/yazi/theme.toml`
* **Windows**: `%AppData%\yazi\config\theme.toml`

## Dark and Light Themes

Yazi automatically loads different default themes based on your terminal's color mode:

* Dark mode: `theme-dark.toml` is used as the base
* Light mode: `theme-light.toml` is used as the base

Your `theme.toml` overrides settings in both default themes.

## Flavors for Advanced Theming

For more granular control over light and dark modes, use flavors:

```toml theme={null}
[flavor]
dark = "catppuccin-mocha"
light = "catppuccin-latte"
```

Then create separate flavor files in `~/.config/yazi/flavors/`.

## Style Syntax

Styles are defined using TOML tables with the following fields:

<ParamField path="fg" type="string">
  Foreground color. See [Colors](#colors) section.
</ParamField>

<ParamField path="bg" type="string">
  Background color. See [Colors](#colors) section.
</ParamField>

<ParamField path="bold" type="boolean">
  Bold text when `true`
</ParamField>

<ParamField path="italic" type="boolean">
  Italic text when `true`
</ParamField>

<ParamField path="underline" type="boolean">
  Underlined text when `true`
</ParamField>

<ParamField path="reversed" type="boolean">
  Swap foreground and background colors when `true`
</ParamField>

### Colors

Colors can be specified as:

* **Named colors**: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `gray`
* **Light variants**: `lightred`, `lightgreen`, `lightyellow`, `lightblue`, `lightmagenta`, `lightcyan`
* **Dark variants**: `darkgray`, `darkred`, `darkgreen`, `darkyellow`, `darkblue`, `darkmagenta`, `darkcyan`
* **RGB hex**: `#RRGGBB` (e.g., `#ff0000` for red)
* **Special**: `reset` to use terminal default

### Example Styles

```toml theme={null}
# Simple color
cwd = { fg = "cyan" }

# Multiple attributes
find_keyword = { fg = "yellow", bold = true, italic = true }

# Background color
marker_copied = { fg = "lightgreen", bg = "lightgreen" }

# Reversed colors
active = { reversed = true }

# Empty style
overall = {}
```

## Configuration Sections

### \[flavor] - Theme Flavors

```toml theme={null}
[flavor]
dark = ""   # Flavor for dark mode (empty = use default)
light = ""  # Flavor for light mode (empty = use default)
```

### \[app] - Overall App Style

```toml theme={null}
[app]
overall = {}  # Overall app styling
```

### \[mgr] - File Manager

```toml theme={null}
[mgr]
cwd = { fg = "cyan" }  # Current working directory

# Find
find_keyword = { fg = "yellow", bold = true, italic = true, underline = true }
find_position = { fg = "magenta", bg = "reset", bold = true, italic = true }

# Symlinks
symlink_target = { italic = true }

# Selection markers
marker_copied = { fg = "lightgreen", bg = "lightgreen" }
marker_cut = { fg = "lightred", bg = "lightred" }
marker_marked = { fg = "lightcyan", bg = "lightcyan" }
marker_selected = { fg = "lightyellow", bg = "lightyellow" }
marker_symbol = "│"

# Counts
count_copied = { fg = "white", bg = "green" }
count_cut = { fg = "white", bg = "red" }
count_selected = { fg = "black", bg = "yellow" }

# Borders
border_symbol = "│"
border_style = { fg = "gray" }

# Syntax highlighting theme (for code preview)
syntect_theme = ""
```

### \[tabs] - Tab Bar

```toml theme={null}
[tabs]
active = { bg = "blue", bold = true }
inactive = { fg = "blue", bg = "gray" }

# Tab separators
sep_inner = { open = "", close = "" }
sep_outer = { open = "", close = "" }
```

### \[mode] - Mode Indicator

```toml theme={null}
[mode]
# Normal mode
normal_main = { bg = "blue", bold = true }
normal_alt = { fg = "blue", bg = "gray" }

# Select mode
select_main = { bg = "red", bold = true }
select_alt = { fg = "red", bg = "gray" }

# Unset mode
unset_main = { bg = "red", bold = true }
unset_alt = { fg = "red", bg = "gray" }
```

### \[indicator] - File Indicator

```toml theme={null}
[indicator]
parent = { reversed = true }
current = { reversed = true }
preview = { underline = true }
padding = { open = "", close = "" }
```

### \[status] - Status Bar

```toml theme={null}
[status]
overall = {}
sep_left = { open = "", close = "" }
sep_right = { open = "", close = "" }

# File permissions
perm_sep = { fg = "darkgray" }
perm_type = { fg = "green" }
perm_read = { fg = "yellow" }
perm_write = { fg = "red" }
perm_exec = { fg = "cyan" }

# Progress bars
progress_label = { bold = true }
progress_normal = { fg = "green", bg = "black" }
progress_error = { fg = "yellow", bg = "red" }
```

### \[which] - Which-Key Popup

```toml theme={null}
[which]
cols = 3
mask = { bg = "black" }
cand = { fg = "lightcyan" }
rest = { fg = "darkgray" }
desc = { fg = "lightmagenta" }
separator = "  "
separator_style = { fg = "darkgray" }
```

### \[confirm] - Confirmation Dialog

```toml theme={null}
[confirm]
border = { fg = "blue" }
title = { fg = "blue" }
body = {}
list = {}
btn_yes = { reversed = true }
btn_no = {}
btn_labels = ["  [Y]es  ", "  (N)o  "]
```

### \[spot] - File Details Spotter

```toml theme={null}
[spot]
border = { fg = "blue" }
title = { fg = "blue" }

# Table
tbl_col = { fg = "blue" }
tbl_cell = { fg = "yellow", reversed = true }
```

### \[notify] - Notifications

```toml theme={null}
[notify]
title_info = { fg = "green" }
title_warn = { fg = "yellow" }
title_error = { fg = "red" }

icon_info = ""
icon_warn = ""
icon_error = ""
```

### \[pick] - Picker Dialog

```toml theme={null}
[pick]
border = { fg = "blue" }
active = { fg = "magenta", bold = true }
inactive = {}
```

### \[input] - Input Dialog

```toml theme={null}
[input]
border = { fg = "blue" }
title = {}
value = {}
selected = { reversed = true }
```

### \[cmp] - Completion Popup

```toml theme={null}
[cmp]
border = { fg = "blue" }
active = { reversed = true }
inactive = {}

icon_file = ""
icon_folder = ""
icon_command = ""
```

### \[tasks] - Task Manager

```toml theme={null}
[tasks]
border = { fg = "blue" }
title = {}
hovered = { fg = "magenta", bold = true }
```

### \[help] - Help Menu

```toml theme={null}
[help]
on = { fg = "cyan" }
run = { fg = "magenta" }
desc = {}
hovered = { reversed = true, bold = true }
footer = { fg = "black", bg = "white" }
```

### \[filetype] - File Type Colors

Define colors for different file types:

```toml theme={null}
[filetype]
rules = [
  # Images
  { mime = "image/*", fg = "yellow" },
  
  # Media
  { mime = "{audio,video}/*", fg = "magenta" },
  
  # Archives
  { mime = "application/{zip,rar,7z*,tar,gzip}", fg = "red" },
  
  # Documents
  { mime = "application/{pdf,doc,rtf}", fg = "cyan" },
  
  # VFS files
  { mime = "vfs/{absent,stale}", fg = "gray" },
  
  # Special files
  { url = "*", is = "orphan", bg = "red" },
  { url = "*", is = "exec", fg = "green" },
  { url = "*", is = "dummy", bg = "red" },
  
  # Directories
  { url = "*/", fg = "blue" },
]
```

Rule fields:

* `mime` - Match by MIME type pattern
* `url` - Match by URL pattern
* `is` - Match by file property: `orphan`, `exec`, `dummy`, `link`, `block`, `char`, `fifo`, `sock`, `sticky`
* `fg` - Foreground color
* `bg` - Background color

### \[icon] - File and Folder Icons

Define custom icons for files and folders:

```toml theme={null}
[icon]
globs = []  # Reserved for future use

# Directory icons
dirs = [
  { name = ".config", text = "", fg = "#ff9800" },
  { name = ".git", text = "", fg = "#00bcd4" },
  { name = "Downloads", text = "", fg = "#00bcd4" },
]

# File icons by name
files = [
  { name = "README.md", text = "󰂺", fg = "#ededed" },
  { name = "Makefile", text = "", fg = "#6d8086" },
  { name = "package.json", text = "", fg = "#e8274b" },
]

# File icons by extension
exts = [
  { name = "rs", text = "", fg = "#dea584" },
  { name = "js", text = "", fg = "#cbcb41" },
  { name = "py", text = "", fg = "#ffbc03" },
  { name = "md", text = "", fg = "#dddddd" },
]

# Icons by file condition
conds = [
  { if = "dir", text = "", fg = "#03a9f4" },
  { if = "exec", text = "", fg = "#8bc34a" },
  { if = "link", text = "", fg = "#9e9e9e" },
  { if = "orphan", text = "", fg = "#ffffff" },
  { if = "!dir", text = "", fg = "#ffffff" },
]
```

Icon conditions (`if` field):

* `dir` - Directories
* `exec` - Executable files
* `link` - Symbolic links
* `orphan` - Broken symlinks
* `block` - Block devices
* `char` - Character devices
* `fifo` - Named pipes
* `sock` - Sockets
* `sticky` - Files with sticky bit
* `dummy` - Dummy files
* `!dir` - Non-directories (fallback)

## Complete Example

```toml theme={null}
"$schema" = "https://yazi-rs.github.io/schemas/theme.json"

[flavor]
dark = ""
light = ""

[mgr]
cwd = { fg = "cyan" }
find_keyword = { fg = "yellow", bold = true }
marker_selected = { fg = "lightyellow", bg = "lightyellow" }
border_style = { fg = "gray" }

[tabs]
active = { bg = "blue", bold = true }
inactive = { fg = "blue", bg = "gray" }

[status]
progress_normal = { fg = "green", bg = "black" }

[filetype]
rules = [
  { mime = "image/*", fg = "yellow" },
  { mime = "video/*", fg = "magenta" },
  { url = "*/", fg = "blue" },
]

[icon]
exts = [
  { name = "rs", text = "", fg = "#dea584" },
  { name = "js", text = "", fg = "#cbcb41" },
]
conds = [
  { if = "dir", text = "", fg = "#03a9f4" },
  { if = "!dir", text = "", fg = "#ffffff" },
]
```

## Tips

### Using Nerd Fonts

Many icon glyphs require [Nerd Fonts](https://www.nerdfonts.com/). Make sure your terminal uses a Nerd Font to display icons correctly.

### Color Schemes

Popular color schemes for Yazi:

* **Catppuccin**: Soothing pastel theme
* **Tokyo Night**: Dark theme inspired by Tokyo's night
* **Nord**: Arctic, north-bluish color palette
* **Gruvbox**: Retro groove color scheme

Check the [Yazi Flavors](https://yazi-rs.github.io/docs/flavors/overview) for pre-made themes.

### Testing Colors

To test your theme changes:

1. Save your `theme.toml`
2. Reload Yazi (or restart it)
3. Check the appearance
4. Iterate on colors until satisfied

## See Also

* [Yazi Configuration](configuration/yazi)
* [Keymap Configuration](configuration/keymap)
* [Flavors Documentation](https://yazi-rs.github.io/docs/flavors/overview)