What are <leader> and <localleader> keys?

[hlissner]

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”