Global keybindings (use-package User Manual)

4.2.1 Global keybindings

To bind keys globally, the :bind keyword takes as its argument either a single cons or a list of conses. Each cons has the form (key . command), where key is a string indicating the key to bind, and command is the name of a command (a symbol). The syntax for the keys is similar to the syntax used by the kbd function (see Init Rebinding in GNU Emacs Manual, for more information).

Using :bind with a single cons

Here is an example of using a single cons:

(use-package ace-jump-mode
 :bind ("C-." . ace-jump-mode))

This does two things: first, it creates an autoload for the ace-jump-mode command and defers loading of the ace-jump-mode package until you actually use it. Second, it binds the key C-. to that command globally.

Using :bind with a list of conses

Here is an example of using :bind with a list of conses:

(use-package hi-lock
 :bind (("M-o l" . highlight-lines-matching-regexp)
 ("M-o r" . highlight-regexp)
 ("M-o w" . highlight-phrase)))

This binds the three key sequences to the corresponding commands.

Using special keys

Inside key strings, special keys like TAB or F1–F12 have to be written inside angle brackets, e.g., "C-<up>". Standalone special keys (and some combinations) can be written in square brackets, e.g. [tab] instead of "<tab>".

Examples:

(use-package helm
 :bind (("M-x" . helm-M-x)
 ("M-<f5>" . helm-find-files)
 ([f10] . helm-buffers-list)
 ([S-f10] . helm-recentf)))

Remapping commands

Remapping of commands with :bind and bind-key works as expected, because when the binding is a vector, it is passed straight to define-key. See Remapping Commands in GNU Emacs Lisp Reference Manual, for more information about command remapping. For example, the following declaration will rebind fill-paragraph (bound to M-q by default) to unfill-toggle:

(use-package unfill
 :bind ([remap fill-paragraph] . unfill-toggle))

What :bind does behind the scenes

To understand what :bind does behind the scenes, it might be useful to consider an example:

(use-package ace-jump-mode
 :bind ("C-." . ace-jump-mode))

This could be expressed in a much more verbose way with the :commands and :init keywords:

(use-package ace-jump-mode
 :commands ace-jump-mode
 :init
 (bind-key "C-." 'ace-jump-mode))

Without using even the :commands keyword, we could also write the above like so:

(use-package ace-jump-mode
 :defer t
 :init
 (autoload 'ace-jump-mode "ace-jump-mode" nil t)
 (bind-key "C-." 'ace-jump-mode))

Although these three forms are all equivalent, the first form is usually the best, as it will save some typing.

Next: Key bindings in local keymaps, Up: Key bindings [Contents][Index]