2021-06-17 13:08:05 +02:00
# Key Remapping
One-way key remapping is temporarily supported via a simple TOML configuration
file. (More powerful solutions such as rebinding via commands will be
2021-10-23 01:54:02 +02:00
available in the future).
2021-06-17 13:08:05 +02:00
To remap keys, write a `config.toml` file in your `helix` configuration
directory (default `~/.config/helix` in Linux systems) with a structure like
this:
```toml
# At most one section each of 'keys.normal', 'keys.insert' and 'keys.select'
[keys.normal]
book: Refer to keys by key names, not representations
This is an attempt to clean up the inconsistent way that keys are
written in various places. These rules require the fewest changes to the
existing text.
Use the "Key name", as defined in remapping.md, which uses
"Some-Modifiers-PascalCaseKey". The "Representation", which uses
"S-M-lowercasekey", is only used for configuration entries.
For key combinations which do not present a popup, just present the keys
one after the other, with no intervening space, like `]p`.
For key combinations which present a popup, separate them with ` + `,
like `Space + f`.
The Ctrl modifier is called Ctrl, not Control.
2022-10-10 20:32:05 +02:00
C-s = ":w" # Maps the Ctrl-s to the typable command :w which is an alias for :write (save file)
C-o = ":open ~/.config/helix/config.toml" # Maps the Ctrl-o to opening of the helix config file
2021-06-17 13:08:05 +02:00
a = "move_char_left" # Maps the 'a' key to the move_char_left command
w = "move_line_up" # Maps the 'w' key move_line_up
book: Refer to keys by key names, not representations
This is an attempt to clean up the inconsistent way that keys are
written in various places. These rules require the fewest changes to the
existing text.
Use the "Key name", as defined in remapping.md, which uses
"Some-Modifiers-PascalCaseKey". The "Representation", which uses
"S-M-lowercasekey", is only used for configuration entries.
For key combinations which do not present a popup, just present the keys
one after the other, with no intervening space, like `]p`.
For key combinations which present a popup, separate them with ` + `,
like `Space + f`.
The Ctrl modifier is called Ctrl, not Control.
2022-10-10 20:32:05 +02:00
"C-S-esc" = "extend_line" # Maps Ctrl-Shift-Escape to extend_line
2021-08-18 02:53:50 +02:00
g = { a = "code_action" } # Maps `ga` to show possible code actions
2021-11-11 05:44:50 +01:00
"ret" = ["open_below", "normal_mode"] # Maps the enter key to open_below then re-enter normal mode
2021-06-17 13:08:05 +02:00
[keys.insert]
2021-08-18 02:53:50 +02:00
"A-x" = "normal_mode" # Maps Alt-X to enter normal mode
j = { k = "normal_mode" } # Maps `jk` to exit insert mode
2021-06-17 13:08:05 +02:00
```
2021-12-08 16:26:33 +01:00
> NOTE: Typable commands can also be remapped, remember to keep the `:` prefix to indicate it's a typable command.
2021-06-17 13:08:05 +02:00
book: Refer to keys by key names, not representations
This is an attempt to clean up the inconsistent way that keys are
written in various places. These rules require the fewest changes to the
existing text.
Use the "Key name", as defined in remapping.md, which uses
"Some-Modifiers-PascalCaseKey". The "Representation", which uses
"S-M-lowercasekey", is only used for configuration entries.
For key combinations which do not present a popup, just present the keys
one after the other, with no intervening space, like `]p`.
For key combinations which present a popup, separate them with ` + `,
like `Space + f`.
The Ctrl modifier is called Ctrl, not Control.
2022-10-10 20:32:05 +02:00
Ctrl, Shift and Alt modifiers are encoded respectively with the prefixes
2021-06-17 13:08:05 +02:00
`C-` , `S-` and `A-` . Special keys are encoded as follows:
2021-06-20 04:47:22 +02:00
| Key name | Representation |
| --- | --- |
| Backspace | `"backspace"` |
| Space | `"space"` |
| Return/Enter | `"ret"` |
| \- | `"minus"` |
| Left | `"left"` |
| Right | `"right"` |
| Up | `"up"` |
2021-11-08 16:14:03 +01:00
| Down | `"down"` |
2021-06-20 04:47:22 +02:00
| Home | `"home"` |
| End | `"end"` |
2021-12-06 04:24:25 +01:00
| Page Up | `"pageup"` |
| Page Down | `"pagedown"` |
2021-06-20 04:47:22 +02:00
| Tab | `"tab"` |
| Delete | `"del"` |
| Insert | `"ins"` |
| Null | `"null"` |
| Escape | `"esc"` |
2021-06-17 13:08:05 +02:00
2021-09-13 10:48:12 +02:00
Keys can be disabled by binding them to the `no_op` command.
2021-11-22 15:44:42 +01:00
Commands can be found at [Keymap ](https://docs.helix-editor.com/keymap.html ) Commands.
2021-12-08 16:26:33 +01:00
> Commands can also be found 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`.
