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:

[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:

fg · string

Foreground color. See Colors section.

bg · string

Background color. See Colors section.

bold · boolean

Bold text when true

italic · boolean

Italic text when true

underline · boolean

Underlined text when true

reversed · boolean

Swap foreground and background colors when true

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

# 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

[flavor]
dark = ""   # Flavor for dark mode (empty = use default)
light = ""  # Flavor for light mode (empty = use default)

[app] - Overall App Style

[app]
overall = {}  # Overall app styling

[mgr] - File Manager

[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

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

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

[mode] - Mode Indicator

[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

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

[status] - Status Bar

[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

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

[confirm] - Confirmation Dialog

[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

[spot]
border = { fg = "blue" }
title = { fg = "blue" }

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

[notify] - Notifications

[notify]
title_info = { fg = "green" }
title_warn = { fg = "yellow" }
title_error = { fg = "red" }

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

[pick] - Picker Dialog

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

[input] - Input Dialog

[input]
border = { fg = "blue" }
title = {}
value = {}
selected = { reversed = true }

[cmp] - Completion Popup

[cmp]
border = { fg = "blue" }
active = { reversed = true }
inactive = {}

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

[tasks] - Task Manager

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

[help] - Help Menu

[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:

[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:

[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

"$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. 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 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
• Keymap Configuration
• Flavors Documentation