git.iko.soy/helix
on bbcdcd0 help sign in
helix/book/src/remapping.md
79 lines 2.9 kB history raw
1# Key remapping
3Helix currently supports one-way key remapping through a simple TOML configuration
4file. (More powerful solutions such as rebinding via commands will be
5available in the future).
7To remap keys, create a `config.toml` file in your `helix` configuration
8directory (default `~/.config/helix` on Linux systems) with a structure like
9this:
11```toml
12# At most one section each of 'keys.normal', 'keys.insert' and 'keys.select'
13[keys.normal]
14C-s = ":w" # Maps Ctrl-s to the typable command :w which is an alias for :write (save file)
15C-o = ":open ~/.config/helix/config.toml" # Maps Ctrl-o to opening of the helix config file
16a = "move_char_left" # Maps the 'a' key to the move_char_left command
17w = "move_line_up" # Maps the 'w' key move_line_up
18"C-S-esc" = "extend_line" # Maps Ctrl-Shift-Escape to extend_line
19g = { a = "code_action" } # Maps `ga` to show possible code actions
20"ret" = ["open_below", "normal_mode"] # Maps the enter key to open_below then re-enter normal mode
22[keys.insert]
23"A-x" = "normal_mode" # Maps Alt-X to enter normal mode
24j = { k = "normal_mode" } # Maps `jk` to exit insert mode
25```
27## Minor modes
29Minor modes are accessed by pressing a key (usually from normal mode), giving access to dedicated bindings. Bindings
30can be modified or added by nesting definitions.
32```toml
33[keys.insert.j]
34k = "normal_mode" # Maps `jk` to exit insert mode
36[keys.normal.g]
37a = "code_action" # Maps `ga` to show possible code actions
39# invert `j` and `k` in view mode
40[keys.normal.z]
41j = "scroll_up"
42k = "scroll_down"
44# create a new minor mode bound to `+`
45[keys.normal."+"]
46m = ":run-shell-command make"
47c = ":run-shell-command cargo build"
48t = ":run-shell-command cargo test"
49```
51## Special keys and modifiers
53Ctrl, Shift and Alt modifiers are encoded respectively with the prefixes
54`C-`, `S-` and `A-`. Special keys are encoded as follows:
56| Key name | Representation |
57| --- | --- |
58| Backspace | `"backspace"` |
59| Space | `"space"` |
60| Return/Enter | `"ret"` |
61| \- | `"minus"` |
62| Left | `"left"` |
63| Right | `"right"` |
64| Up | `"up"` |
65| Down | `"down"` |
66| Home | `"home"` |
67| End | `"end"` |
68| Page Up | `"pageup"` |
69| Page Down | `"pagedown"` |
70| Tab | `"tab"` |
71| Delete | `"del"` |
72| Insert | `"ins"` |
73| Null | `"null"` |
74| Escape | `"esc"` |
76Keys can be disabled by binding them to the `no_op` command.
78A list of commands is available in the [Keymap](https://docs.helix-editor.com/keymap.html) documentation
79 and in the source code at [`helix-term/src/commands.rs`](https://github.com/helix-editor/helix/blob/master/helix-term/src/commands.rs) at the invocation of `static_commands!` macro and the `TypableCommandList`.