Emacs Docs

Appearance

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:

emacs-lisp
(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:

emacs-lisp
(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:

emacs-lisp
(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:

emacs-lisp
(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:

emacs-lisp
(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:

emacs-lisp
(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:

emacs-lisp
(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.