How to Use the Vim <leader> KeyPublished: - Last Modified:
Vim is a keyboard driven text editor which means there are a lot of keyboard shortcuts and commands. The <leader> key is a vim tool that can be used to create personalized shortcuts. Let’s discuss a few different ways to create our own shortcuts.
Change the <leader> key
The default <leader> key is a backslash
\. To change the leader key to the comma
, add let mapleader = “,” to your vimrc (to use the space key add let mapleader = “ “). Reload vim and test your new <leader> key.
let mapleader = " " " map leader to Space let mapleader = "," " map leader to comma
The leader key can be whatever key you choose. I map mine to the comma key. Used keys will be replaced if you set them to the <leader> key so only use a key you are comfortable overwriting (Space and comma are popular leader keys. To find out what a key may be used for run
By default you have 1000ms after typing your leader key to type your shortcut. That value can be adjusted by setting
timeoutlen in your vimrc
set timeoutlen 500 " Set timeout length to 500 ms
Vim, by default, shows no feedback for this timeout length. Add
set showcmd to your vimrc and it will show your leader key in the bottom right corner for the duration of the timeout.
Mapping vim commands
Vim search has one small feature that is useful but cumbersome. All search terms found are highlighted until your next search. You can type
This can be a little verbose, however. With the power of the <leader> key, it takes only two keystrokes instead of four (including the colon). Add this to your vimrc
map <leader>h :noh<CR>
Now highlights can be hidden by typing
,h in normal mode. If you have
set hlsearch in your vimrc your next search will be highlighted.
Mapping Custom Functions
The <leader> key can also be used with custom methods. Create a function in your vimrc to toggle both relative and normal line numbers but not relative when using versions before vim 7.4.
function! ToggleLineNumber() if v:version > 703 set norelativenumber! endif set nonumber! endfunction
You can type
:ToggleLineNumber() to toggle the line numbers or you can add this to your vimrc
map <leader>r :call ToggleLineNumber()<CR>
,r and the line numbers toggle for every version of vim without errors for unknown functions.
Mapping Plugin Functions
The <leader> key can also be used for plugin functions. For example, NERDTree is an alternative file browser for vim. The NERDTree docs suggest you add
map <C-n> :NERDTreeToggle<CR>
to your vimrc to toggle the NERDTree buffer. To use a <leader> shortcut add this to your vimrc.
map <leader>t :NERDTreeToggle<CR>
,t toggles the NERDTree buffer and you can browse the file structure and open files as normal.
" Automatically close NERDTree when you open a file let NERDTreeQuitOnOpen=1
Bonus tip: Use multiple leader keys
If you run out of key combinations or you want to separate different function types you can have multiple <leader> keys.
let mapleader="," map <leader>n :set number<CR> let mapleader="-" map <leader>n :set nonumber<CR>
,n will display line numbers and
-n will hide line numbers.
There are many more uses of the <leader> key. What kind of shortcuts can you come up with?
Final Vimrc settings
let mapleader = "," " map leader to comma set timeoutlen 500 " Set timeout length to 500 ms " Custom function function! ToggleLineNumber() if v:version > 703 set norelativenumber! endif set nonumber! endfunction " Custom shortcuts map <leader>h :noh<CR> map <leader>r :call ToggleLineNumber()<CR> map <leader>t :NERDTreeToggle<CR> map <leader>n :set number<CR> " Automatically close NERDTree when you open a file let NERDTreeQuitOnOpen=1 " Alternative leader and shortcut let mapleader="-" map <leader>n :set nonumber<CR>