Binding to a keymap (use-package User Manual)

4.2.3 Binding to keymaps ¶

Normally :bind expects that commands are functions that will be autoloaded from the given package. However, this does not work if one of those commands is actually a keymap, since keymaps are not functions, and cannot be autoloaded using the built-in autoload function.

When you define a keymap using defvar-keymap you can add the required function definition by including :prefix t in the keymap definition (see Creating Keymaps in GNU Emacs Lisp Reference Manual).

For example:

(defvar-keymap foo-command-map
 :doc "A keymap that returns a function"
 :prefix t
 "A" #'foo-command-a
 "B" #'foo-command-b)
(use-package foo
 :bind (("C-c p" . foo-command-map)))

would create the bindings for the key sequences "C-c p A", and "C-c p B" for package foo.

Alternatively, to handle this case, use-package offers a special, limited variant of :bind called :bind-keymap. The only difference is that the “commands” bound to by :bind-keymap must be keymaps defined in the package, rather than interactive functions. This is handled behind the scenes by generating custom code that loads the package containing the keymap, and then re-executes your keypress after the first load, to reinterpret that keypress as a prefix key.

For example:

(use-package foo
 :bind-keymap ("C-c p" . foo-command-map))