What are <leader> and <localleader> keys?

hlissner · November 2, 2020, 8:52pm

Doom strives for a totally keyboard driven environment, but there are more commands out there than you have keys, so I bind them under a common “prefix”.

A “prefix” is a key that begins a key sequence. For instance, the key sequence C-xC-kb is comprised of three distinct input events. Both C-x and C-xC-k can be considered prefixes.

Doom borrows two concepts from Vim:

The “leader” key: a global prefix under which the most common commands are centralized. This is treated like a keyboard analog to the menu bar and is intended to be available anywhere.
The “local leader” key (or buffer/mode-local leader key): a contextual leader prefix. In other words, a prefix whose sub-bindings change depending on what major mode (language) your in, or minor modes you have active.

In technical writing, these two keys are often referred to as <leader> and <localleader>.

Where are Doom’s leader keys?

Veteran vimmers may prefer their leader keys on , or \. As with anything in Emacs, this can be customized.

Doom’s leader and localleader keys are on different prefixes depending on whether you have Evil (our vim emulation layer) enabled.

If evil is enabled:
- SPC and SPCm in any mode but insert mode, respectively.
- M-SPC and M-SPCm in insert or emacs mode. (A separate key is needed as not to override the default behavior of SPC – to insert whitespace).
If evil is disabled: C-c and C-cl instead.

Changing the leader prefixes

Four variables control what prefixes Doom uses for its leader and localleader keys:

For Evil users:
- doom-leader-key (default: "SPC")
- doom-localleader-key (default: "SPC m")
For Emacs and Insert state (evil users), and non-evil users:
- doom-leader-alt-key (default: "M-SPC" for evil users, "C-c" otherwise)
- doom-localleader-alt-key (default: "M-SPC m" for evil users, "C-c l" otherwise)

For example, to change your leader keys to , and \:

;;; add to ~/.doom.d/config.el
(setq doom-leader-key ","
      doom-localleader-key "\\")

When evil is disabled neither doom-leader-key and doom-localleader-key are used. Change doom-leader-alt-key and doom-localleader-alt-key instead.

Binding new leader keys

To add your own leader keybinds use the map! macro:

(map! :leader 
      ;; <leader> x will invoke the dosomething command
      "x" #'dosomething
      ;; <leader> y will print "Hello world" in the minibuffer
      "y" (cmd! (message "Hello world"))
      ;; This unbinds what was previously bound to <leader> f
      "f" nil)

Local leaders keys, on the other hand, require a :map to be specified:

(map! :after python
      :map python-mode-map
      :localleader
      ;; <localleader> x will invoke the dosomething command
      "x" #'dosomething
      ...)

You’ll notice :after python in the example above. It is important that your keys are bound after the keymap is loaded. In this case, python-mode-map is defined in the python package. See “How to bind (or rebind) keys”