# Mapping

**URL:** <https://discuss.kakoune.com/t/mapping/547>\
**Category:** Manual++\
**Created:** [May 8, 2019, 2:23am UTC](https://discuss.kakoune.com/t/mapping/547 "2019-05-08T02:23:16Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![robertmeta](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/robertmeta/32/833_2.png) [@robertmeta](https://discuss.kakoune.com/u/robertmeta)\
**Post date:** [May 8, 2019, 2:23am UTC](https://discuss.kakoune.com/t/mapping/547/1 "2019-05-08T02:23:16Z")

</div>

# Description

Creating and removing shortcuts boils down to the following commands,  
respectively:

```
map [switches] <scope> <mode> <key> <keys>
unmap <scope> <mode> <key> [<expected>]

```

The **map** command makes **key** behave as if the **keys** sequence was  
typed.

**mode** dictates in what context the mapping will be available:

**insert**  
insert mode

**normal**  
normal mode

**prompt**  
prompts, such as when entering a command through **:** , or a regex  
through **/**

**menu**  
mode entered when a menu is displayed with the _menu_ command

**user**  
mode entered when the user prefix is hit (default: _,_)

**goto**  
mode entered when the goto key is hit (default: _g_)

**view**  
mode entered when the view key is hit (default: _v_)

**object**  
mode entered when an object selection is triggered (e.g. _\<a-i\>_)

The context of execution of the above modes is always the current one at  
the time of execution of the mapping, except for **user** mode (always  
executed in a _normal_ context). Refer to [`:doc modes`](https://discuss.kakoune.com/t/modes/548/2) for  
more details.

An optional **-docstring** switch followed by a string can be used to  
describe what the mapping does. This docstring will be used in autoinfo  
boxes.

The **unmap** command removes a mapping of **key** in the given  
**scope** and **mode**. If **expected** is specified, the mapping is  
removed only if it is set to the same sequence of keys passed using the  
**expected** argument.

For more information about the values of the **scope** parameter, refer  
to [`:doc scopes`](https://discuss.kakoune.com/t/scopes/552/2).

# Mapping commands

It’s common to use a normal-mode or user-mode mapping to trigger a  
command, like this:

```
map global user n ': make-next-error<ret>'

```

Note the space between the `:` and the command. This prevents Kakoune  
from adding this command to the prompt history, so the user won’t have  
to scroll past it to review commands they actually typed.

If you make a normal-mode mapping, you can prefix it with a count or a  
register name like any other normal-mode key. You can forward this  
information to the command you invoke with the `%val{count}` and  
`%val{register}` expansions (See  
[:doc expansions](https://discuss.kakoune.com/t/expansions/540/2)). For example:

```
map global normal = ': echo Got count %val{count} and reg %val{register}<ret>'

```

# Mappable keys

See [`:doc keys`](https://discuss.kakoune.com/t/keys-keybindings/546/2) to discover the list of default bindings.

For **key** and **keys** in the **map** command, the following key names  
can be used:

**x** , **\<x\>**  
Most keys, especially alphabetic keys, represent themselves. Keys can  
also be wrapped in angle-brackets for consistency with the  
non-alphabetic keys below.

**\<c-x\>**  
Holding down Control while pressing the **x** key.

**\<a-x\>**  
Holding down Alt while pressing the **x** key.

**\<s-x\>** , **X** , **\<X\>** , **\<s-X\>**  
Holding down Shift while pressing the **x** key. **\<s-x\>** ,  
**\<s-X\>** and **\<X\>** are treated as the same key. The  
**s-** modifier only works with ASCII letters and cannot be used with  
other printable keys (non-ASCII letters, digits, punctuation) because  
their shift behaviour depends on your keyboard layout. The **s-**  
modifier _can_ be used with special keys like **\<up\>** and  
**\<tab\>**.

**\<c-a-x\>**  
Holding down Control and Alt while pressing the **x** key.

**\<lt\>** , **\<gt\>**  
The **\<** and **\>** characters.

**\<plus\>** , **\<minus\>**  
The **+** and **-** characters.

**\<ret\>**  
The Return or Enter key.

**\<space\>**  
The space bar.

**\<tab\>**  
The Tab key.

**\<backspace\>**  
The Backspace (delete to the left) key.

**\<del\>**  
The Delete (to the right) key.

**\<esc\>**  
The Escape key.

**\<up\>** , **\<down\>** , **\<left\>** , **\<right\>** ; **\<pageup\>** , **\<pagedown\>** , **\<home\>** , **\<end\>**  
The usual cursor-movement keys.

**\<f1\>** , **\<f2\>** , … **\<f12\>**  
Function keys.

> **Note**
> 
> Although Kakoune allows many key combinations to be mapped, not every  
> possible combination can be triggered. For example, due to limitations  
> in the way terminals handle control characters, mappings like  
> **\<c-s-a\>** are unlikely to work in Kakoune’s terminal UI.