Skip to main content

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.

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

Build docs developers (and LLMs) love

Get started for freeTalk to us