Keymap Overview

Yazi's keybinding system is organized into 8 layers, each corresponding to a UI component. Key events are dispatched to the active layer depending on which component has focus.

The 8 Layers

Layer	Component	Trigger
[mgr]	File list (manager)	Default view
[tasks]	Task manager	T or Ctrl+T
[spot]	File info spotter	;
[pick]	Selection picker	Plugin prompts, filter dialogs
[input]	Text input	Rename (r), create (n), filter (f), search (/)
[confirm]	Confirmation dialog	Destructive operations
[cmp]	Completion menu	Tab-completion suggestions
[help]	Help menu	F1 or ~

Keymap Priority: prepend vs append

Keybindings inside keymap.toml use two arrays that control priority:

• prepend_keymap — Higher priority. Bindings listed here take precedence over default bindings and previously loaded user bindings.
• append_keymap — Lower priority. Bindings listed here only activate if no higher-priority binding matches the key.

[manager]
prepend_keymap = [
  { on = "g d", run = "cd ~/Documents", desc = "Go to Documents" },
]
append_keymap = [
  { on = "g h", run = "cd ~", desc = "Go to home" },
]

Bindings in prepend_keymap shadow defaults; bindings in append_keymap are fallbacks.

Key Notation

Keys use single-character names or angle-bracket notation for special keys:

Notation	Key
a	Lowercase a
A	Shift + A
<Enter>	Enter/Return
<Tab>	Tab
<Backspace>	Backspace
<Esc>	Escape
<Space>	Space
<Up>, <Down>, <Left>, <Right>	Arrow keys
<C-a>	Ctrl + A
<M-a>	Alt + A (or Option + A / Esc A)
<C-<Space>>	Ctrl + Space

Chords are expressed as space-separated sequences: g d means press g, then d.

Configuration File

Keybindings are defined in ~/.config/yazi/keymap.toml:

[manager]
prepend_keymap = []
append_keymap = []

[tasks]
prepend_keymap = []
append_keymap = []

[spot]
prepend_keymap = []
append_keymap = []

[pick]
prepend_keymap = []
append_keymap = []

[input]
prepend_keymap = []
append_keymap = []

[confirm]
prepend_keymap = []
append_keymap = []

[cmp]
prepend_keymap = []
append_keymap = []

[help]
prepend_keymap = []
append_keymap = []

Layer resolution

When a key is pressed, Yazi checks the active layer's prepend_keymap first, then falls through to append_keymap. If no match is found in either, the key press is ignored.

Keybinding Structure

Each binding is a TOML table with these fields:

Field	Type	Description
on	string or [string]	Key(s) to bind
run	string	Action to execute with optional arguments
desc	string	Human-readable description (shown in help menu)

Example:

{ on = "ctrl+r", run = "plugin reload --args='--sync'", desc = "Reload plugins" }