Evil’s key bindings are stored in a number of different keymaps. Each
state has a global keymap, where the default bindings for that state
are stored. They are named
evil-insert-state-map, and so on. The bindings in these maps are
visible in all buffers currently in the corresponding state.
These keymaps function like ordinary Emacs keymaps and may be modified
using the Emacs function
(define-key evil-normal-state-map (kbd "w") 'some-function)
This binds the key w to the command
some-function in normal
state. The use of
kbd is optional for simple key sequences, like
this one, but recommended in general.
Most of Evil’s bindings are defined in the file
To facilitate shared keybindings between states, some states may activate keybindings from other states as well. For example, motion state bindings are visible in normal and visual state, and normal state bindings are also visible in visual state.
Each state also has a buffer-local keymap which is specific to the
current buffer, and which takes precedence over the global keymap.
These maps are most suitably modified by a mode hook. They are named
(add-hook 'some-mode-hook (lambda () (define-key evil-normal-state-local-map (kbd "w") 'some-function)))
- (evil-global-set-key STATE KEY DEF)¶
Bind KEY to DEF in STATE.
- (evil-local-set-key STATE KEY DEF)¶
Bind KEY to DEF in STATE in the current buffer.
The above examples could therefore have been written as follows:
(evil-global-set-key 'normal (kbd "w") 'some-function) (add-hook 'some-mode-hook (lambda () (evil-local-set-key 'normal (kbd "w") 'some-function)))
Evil provides the macro
evil-define-key for adding state
bindings to ordinary keymaps. It is quite powerful, and is the
preferred method for fine-tuning bindings to activate in specific
- (evil-define-key STATE KEYMAP KEY DEF [BINDINGS...])¶
Create a STATE binding from KEY to DEF for KEYMAP. STATE is one of
emacs, or a list of one or more of these. Omitting a state by using
nilcorresponds to a standard Emacs binding using
define-key. The remaining arguments are like those of
define-key. For example:
(evil-define-key 'normal foo-map "a" 'bar)
This creates a binding from
barin normal state, which is active whenever
foo-mapis active. Using nil for the state, the following lead to identical bindings:
(evil-define-key nil foo-map "a" 'bar) (define-key foo-map "a" 'bar)
It is possible to specify multiple states and/or bindings at once:
(evil-define-key '(normal visual) foo-map "a" 'bar "b" 'foo)
foo-maphas not been initialized yet, this macro adds an entry to
after-load-functions, delaying execution as necessary.
KEYMAP may also be a quoted symbol. If the symbol is
global, the global evil keymap corresponding to the state(s) is used, meaning the following lead to identical bindings:
(evil-define-key 'normal 'global "a" 'bar) (evil-global-set-key 'normal "a" 'bar)
localmay also be used, which corresponds to using
evil-local-set-key. If a quoted symbol is used that is not
local, it is assumed to be the name of a minor mode, in which case
There follows a brief overview of the main functions of this macro.
Define a binding in a given state
(evil-define-key 'state 'global (kbd "key") 'target)
Define a binding in a given state in the current buffer
(evil-define-key 'state 'local (kbd "key") 'target)
Define a binding in a given state under the foo-mode major mode.
(evil-define-key 'state foo-mode-map (kbd "key") 'target)
foo-mode-mapis unquoted, and that this form is safe before
Define a binding in a given state under the bar-mode minor mode.
(evil-define-key 'state 'bar-mode (kbd "key") 'target)
bar-modeis quoted, and that this form is safe before
evil-define-key can be used to augment existing
modes with state bindings, as well as creating packages with custom
bindings. For example, the following will create a minor mode
foo-mode with normal state bindings for the keys w and
(define-minor-mode foo-mode "Foo mode." :keymap (make-sparse-keymap)) (evil-define-key 'normal 'foo-mode "w" 'bar) (evil-define-key 'normal 'foo-mode "e" 'baz)
This minor mode can then be enabled in any buffers where the custom bindings are desired:
(add-hook 'text-mode-hook 'foo-mode) ; enable alongside text-mode
Evil supports a simple implementation of Vim’s leader keys. To bind
a function to a leader key you can use the expression
a key mapping, e.g.
(evil-define-key 'normal 'global (kbd "<leader>fs") 'save-buffer)
Likewise, you can use the expression
<localleader> to mimic Vim’s
local leader, which is designed for mode-specific key bindings.
You can use the function
evil-set-leader to designate
which key acts as the leader and the local leader.
- (evil-set-leader STATE KEY [LOCALLEADER])¶
Set KEY to trigger leader bindings in STATE. KEY should be in the form produced by
kbd. STATE is one of
emacs, a list of one or more of these, or
nil, which means all of the above. If LOCALLEADER is non-nil, set the local leader instead.