> ## 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.

# keymap.toml

> Customize Yazi's keybindings for file management and navigation

The `keymap.toml` file defines all keybindings in Yazi. You can customize existing keybindings or add new ones.

## File Location

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

## Keymap Structure

The keymap file is organized by UI layer. Each layer represents a different part of the interface:

```toml theme={null}
[mgr]      # File manager
[tasks]    # Task manager
[spot]     # File details (spotter)
[pick]     # Picker dialogs
[input]    # Input dialogs
[confirm]  # Confirmation dialogs
[help]     # Help menu
[cmp]      # Completion popup
```

## Keymap Entry Format

Each keybinding is defined as a table in an array:

```toml theme={null}
[[mgr.keymap]]
on = "<key>"
run = "command"
desc = "Description"
```

Or more concisely:

```toml theme={null}
{ on = "<key>", run = "command", desc = "Description" }
```

### Fields

<ParamField path="on" type="string | array" required>
  The key(s) to bind. Can be a single key or an array for key sequences.

  Examples:

  * `"j"` - Single key
  * `"<C-c>"` - Control+C
  * `["g", "g"]` - Key sequence: press 'g' twice
</ParamField>

<ParamField path="run" type="string | array" required>
  The command(s) to execute. Can be a single command or array of commands.

  Examples:

  * `"arrow next"` - Single command
  * `["toggle", "arrow 1"]` - Multiple commands
</ParamField>

<ParamField path="desc" type="string">
  Description shown in help menu and which-key popup
</ParamField>

## Key Syntax

### Basic Keys

Alphanumeric and symbol keys:

```toml theme={null}
on = "a"      # Letter a
on = "1"      # Number 1
on = "-"      # Dash
on = "."      # Period
```

### Special Keys

Special keys use angle brackets:

```toml theme={null}
on = "<Esc>"      # Escape
on = "<Enter>"    # Enter/Return
on = "<Tab>"      # Tab
on = "<Space>"    # Space
on = "<Backspace>" # Backspace
on = "<Delete>"   # Delete

on = "<Up>"       # Arrow up
on = "<Down>"     # Arrow down
on = "<Left>"     # Arrow left
on = "<Right>"    # Arrow right

on = "<PageUp>"   # Page Up
on = "<PageDown>" # Page Down
on = "<Home>"     # Home
on = "<End>"      # End

on = "<F1>"       # Function keys
on = "<F2>"
```

### Modifiers

Modifiers are specified with angle brackets:

```toml theme={null}
on = "<C-c>"      # Ctrl+C
on = "<A-a>"      # Alt+A (Meta on some systems)
on = "<S-PageUp>" # Shift+PageUp
on = "<C-A-d>"    # Ctrl+Alt+D
```

<Note>
  * `<C->` = Control/Ctrl
  * `<A->` = Alt/Option/Meta
  * `<S->` = Shift
</Note>

### Key Sequences

Define multi-key sequences with arrays:

```toml theme={null}
on = ["g", "g"]    # Press 'g' twice
on = ["c", "c"]    # Press 'c' twice
on = [",", "m"]    # Press ',' then 'm'
```

## Manager Layer \[mgr]

The main file manager keybindings.

### Navigation

```toml theme={null}
[[mgr.keymap]]
on = "j"
run = "arrow next"
desc = "Next file"

[[mgr.keymap]]
on = "k"
run = "arrow prev"
desc = "Previous file"

[[mgr.keymap]]
on = "h"
run = "leave"
desc = "Back to parent directory"

[[mgr.keymap]]
on = "l"
run = "enter"
desc = "Enter directory"

[[mgr.keymap]]
on = ["g", "g"]
run = "arrow top"
desc = "Go to top"

[[mgr.keymap]]
on = "G"
run = "arrow bot"
desc = "Go to bottom"
```

### Selection

```toml theme={null}
[[mgr.keymap]]
on = "<Space>"
run = ["toggle", "arrow 1"]
desc = "Toggle selection"

[[mgr.keymap]]
on = "<C-a>"
run = "toggle_all --state=on"
desc = "Select all"

[[mgr.keymap]]
on = "<C-r>"
run = "toggle_all"
desc = "Invert selection"

[[mgr.keymap]]
on = "v"
run = "visual_mode"
desc = "Enter visual mode"
```

### File Operations

```toml theme={null}
[[mgr.keymap]]
on = "y"
run = "yank"
desc = "Copy files"

[[mgr.keymap]]
on = "x"
run = "yank --cut"
desc = "Cut files"

[[mgr.keymap]]
on = "p"
run = "paste"
desc = "Paste files"

[[mgr.keymap]]
on = "d"
run = "remove"
desc = "Move to trash"

[[mgr.keymap]]
on = "D"
run = "remove --permanently"
desc = "Delete permanently"

[[mgr.keymap]]
on = "a"
run = "create"
desc = "Create file/directory"

[[mgr.keymap]]
on = "r"
run = "rename --cursor=before_ext"
desc = "Rename file"
```

### Opening Files

```toml theme={null}
[[mgr.keymap]]
on = "o"
run = "open"
desc = "Open file"

[[mgr.keymap]]
on = "O"
run = "open --interactive"
desc = "Open with picker"

[[mgr.keymap]]
on = "<Enter>"
run = "open"
desc = "Open file"
```

### Search and Filter

```toml theme={null}
[[mgr.keymap]]
on = "s"
run = "search --via=fd"
desc = "Search by name"

[[mgr.keymap]]
on = "S"
run = "search --via=rg"
desc = "Search by content"

[[mgr.keymap]]
on = "f"
run = "filter --smart"
desc = "Filter files"

[[mgr.keymap]]
on = "/"
run = "find --smart"
desc = "Find next"

[[mgr.keymap]]
on = "?"
run = "find --previous --smart"
desc = "Find previous"
```

### Sorting

```toml theme={null}
[[mgr.keymap]]
on = [",", "m"]
run = ["sort mtime --reverse=no", "linemode mtime"]
desc = "Sort by modified time"

[[mgr.keymap]]
on = [",", "M"]
run = ["sort mtime --reverse=yes", "linemode mtime"]
desc = "Sort by modified time (reverse)"

[[mgr.keymap]]
on = [",", "s"]
run = ["sort size --reverse=no", "linemode size"]
desc = "Sort by size"

[[mgr.keymap]]
on = [",", "a"]
run = "sort alphabetical --reverse=no"
desc = "Sort alphabetically"
```

## Input Layer \[input]

Input dialog keybindings (for rename, create, etc.).

```toml theme={null}
[[input.keymap]]
on = "<Enter>"
run = "close --submit"
desc = "Submit input"

[[input.keymap]]
on = "<Esc>"
run = "escape"
desc = "Cancel input"

[[input.keymap]]
on = "i"
run = "insert"
desc = "Enter insert mode"

[[input.keymap]]
on = "a"
run = "insert --append"
desc = "Enter append mode"

[[input.keymap]]
on = "v"
run = "visual"
desc = "Enter visual mode"

# Vim-like movement
[[input.keymap]]
on = "h"
run = "move -1"
desc = "Move left"

[[input.keymap]]
on = "l"
run = "move 1"
desc = "Move right"

[[input.keymap]]
on = "0"
run = "move bol"
desc = "Move to beginning"

[[input.keymap]]
on = "$"
run = "move eol"
desc = "Move to end"
```

## Tasks Layer \[tasks]

Task manager keybindings.

```toml theme={null}
[[tasks.keymap]]
on = "<Esc>"
run = "close"
desc = "Close task manager"

[[tasks.keymap]]
on = "w"
run = "close"
desc = "Close task manager"

[[tasks.keymap]]
on = "k"
run = "arrow prev"
desc = "Previous task"

[[tasks.keymap]]
on = "j"
run = "arrow next"
desc = "Next task"

[[tasks.keymap]]
on = "<Enter>"
run = "inspect"
desc = "Inspect task"

[[tasks.keymap]]
on = "x"
run = "cancel"
desc = "Cancel task"
```

## Confirm Layer \[confirm]

Confirmation dialog keybindings.

```toml theme={null}
[[confirm.keymap]]
on = "<Enter>"
run = "close --submit"
desc = "Confirm"

[[confirm.keymap]]
on = "<Esc>"
run = "close"
desc = "Cancel"

[[confirm.keymap]]
on = "y"
run = "close --submit"
desc = "Yes"

[[confirm.keymap]]
on = "n"
run = "close"
desc = "No"
```

## Complete Example

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

# File Manager
[[mgr.keymap]]
on = "j"
run = "arrow next"
desc = "Next file"

[[mgr.keymap]]
on = "k"
run = "arrow prev"
desc = "Previous file"

[[mgr.keymap]]
on = "<Space>"
run = ["toggle", "arrow 1"]
desc = "Toggle selection"

[[mgr.keymap]]
on = "y"
run = "yank"
desc = "Copy"

[[mgr.keymap]]
on = "p"
run = "paste"
desc = "Paste"

# Task Manager
[[tasks.keymap]]
on = "w"
run = "close"
desc = "Close"

# Input Dialog
[[input.keymap]]
on = "<Enter>"
run = "close --submit"
desc = "Submit"

[[input.keymap]]
on = "<Esc>"
run = "escape"
desc = "Cancel"
```

## Tips

### Override Default Keybindings

You don't need to copy all default keybindings. Just specify the ones you want to change:

```toml theme={null}
# Change only 'j' and 'k' to arrow keys
[[mgr.keymap]]
on = "<Down>"
run = "arrow next"
desc = "Next file"

[[mgr.keymap]]
on = "<Up>"
run = "arrow prev"
desc = "Previous file"
```

### Multiple Commands

Execute multiple commands in sequence:

```toml theme={null}
[[mgr.keymap]]
on = "<Space>"
run = [
  "toggle",      # Toggle selection
  "arrow 1"      # Move down one
]
desc = "Toggle and move"
```

### Command Arguments

Many commands accept arguments:

```toml theme={null}
# Move cursor
run = "arrow 5"          # Move down 5 lines
run = "arrow -3"         # Move up 3 lines
run = "arrow 50%"        # Move down 50%
run = "arrow -100%"      # Move up one page

# Sort
run = "sort mtime --reverse=yes"
run = "sort size --reverse=no"

# Open
run = "open"                    # Use default opener
run = "open --interactive"      # Show opener picker

# Rename
run = "rename --cursor=before_ext"  # Position cursor before extension
run = "rename --cursor=end"         # Position cursor at end
```

## See Also

* [Commands Reference](reference/commands)
* [Yazi Configuration](configuration/yazi)
* [Theme Configuration](configuration/theme)