keymap.toml

Layers

Yazi organizes keybindings into 8 layers:

Layer	Context
[mgr]	Main file manager
[tasks]	Tasks overlay
[spot]	Spotlight preview
[pick]	Pick list
[input]	Input prompt
[confirm]	Confirmation dialog
[cmp]	Completions menu
[help]	Help overlay

Override Modes

Mode	Behavior
prepend_keymap	Higher priority than defaults; recommended for most customizations
append_keymap	Lower priority than defaults
keymap	Full override — replaces all built-in bindings for that layer

tip

Prefer prepend_keymap over keymap to stay compatible with future Yazi updates.

Key Notation

Notation	Key(s)
a – z	Lowercase letters
A – Z	Uppercase letters
<Space>	Space
<Enter>	Enter / Return
<Tab>	Tab
<Esc>	Escape
<Up>, <Down>, <Left>, <Right>	Arrow keys
<F1> – <F19>	Function keys

Modifiers

Prefix	Modifier
<S->	Shift
<C->	Control
<A->	Alt
<D->	Super / Command (macOS)

CSI u Protocol

The CSI u protocol is required for:

• Distinguishing <Tab> from <C-i>
• Distinguishing <Esc> from <C-[>
• Using the <D-> (Super) modifier

Most modern terminals support CSI u. If <D-> bindings do not work, verify your terminal emulator supports this protocol.

Binding Keys

Only one TOML style is allowed per keymap file — either array-of-tables or inline array (not both).

# Array-of-tables style
[[mgr]]
prepend_keymap = [
  { on = "<C-g>", run = "escape", desc = "Cancel" },
]

# Inline array style
[mgr]
prepend_keymap = [
  { on = "<C-g>", run = "escape", desc = "Cancel" },
]

Disabling Keys

Use the noop action to disable a built-in keybinding:

[[mgr]]
prepend_keymap = [
  { on = "<C-s>", run = "noop", desc = "Disable Ctrl-S" },
]