Emacs Docs

Appearance

Selecting commands via completions instead of key bindings ​

As an alternative to reading the list of actions in the verbose or mixed indicators (see the previous section for a description of these), you can press the ‘embark-help-key’, which is ‘C-h’ by default (but you may prefer ‘?’ to free up ‘C-h’ for use as a prefix) after running ‘embark-act’. Pressing the help key will prompt you for the name of an action with completion (but feel free to enter a command that is not among the offered candidates!), and will also remind you of the key bindings. You can press ‘embark-keymap-prompter-key’, which is ‘@’ by default, at the prompt and then one of the key bindings to enter the name of the corresponding action.

You may think that with the ‘*Embark Actions*’ buffer popping up to remind you of the key bindings you’d never want to use completion to select an action by name, but personally I find that typing a small portion of the action name to narrow down the list of candidates feels significantly faster than visually scanning the entire list of actions.

If you find you prefer selecting actions that way, you can configure embark to always prompt you for actions by setting the variable ‘embark-prompter’ to ‘embark-completing-read-prompter’.

On the other hand, you may wish to continue using key bindings for the actions you perform most often, and to use completion only to explore what further actions are available or when you’ve forgotten a key binding. In that case, you may prefer to use the minimal indicator, which does not pop-up an ‘*Embark Actions*’ buffer at all, and to use the ‘embark-help-key’ whenever you need help. This unobtrusive setup is achieved with the following configuration:

emacs-lisp
(setq embark-indicators
      '(embark-minimal-indicator  ; default is embark-mixed-indicator
        embark-highlight-indicator
        embark-isearch-highlight-indicator))

Vertico users may wish to configure a grid display for the actions and key-bindings, reminiscent of the popular package which-key, but, of course, enhanced by the use of completion to narrow the list of commands. In order to get the grid display, put the following in your Vertico configuration:

emacs-lisp
(add-to-list 'vertico-multiform-categories '(embark-keybinding grid))
(vertico-multiform-mode)

This will make the available keys be shown in a compact grid like in ‘which-key’. The ‘vertico-multiform-mode’ also enables keys such as ‘M-V’, ‘M-G’, ‘M-B’, and ‘M-U’ for manually switching between layouts in Vertico buffers.