GNU-devel ELPA - vertico

• Vertical display with arrow key navigation. Many additional display modes are provided as extensions.
• Prompt shows the current candidate index and the total number of candidates.
• The current candidate is inserted with TAB and selected with RET.
• Non-existing candidates can be submitted with M-RET or by moving the point to the prompt.
• Efficient sorting by history position, length and alphabetically.
• Long candidates with newlines are formatted to take up less space.
• Lazy completion candidate highlighting for performance.
• Annotations are displayed next to the candidates (annotation- and affixation-function).
• Support for candidate grouping and group cycling commands (group-function).

Vertico is available from GNU ELPA. You can install it directly via M-x package-install RET vertico RET. After installation, activate the global minor mode with M-x vertico-mode RET.

Vertico defines its own local keymap in the minibuffer which is derived from minibuffer-local-map. The keymap keeps most of the fundamental-mode keybindings intact and remaps and binds only a handful of commands.

Note in particular the binding of TAB to vertico-insert, which inserts the currently selected candidate, and the binding of RET and M-RET to vertico-exit and vertico-exit-input respectively.

vertico-exit exits with the currently selected candidate, while vertico-exit-input exits with the minibuffer input instead. Exiting with the current input is needed when you want to create a new buffer or a new file with find-file or switch-to-buffer. As an alternative to pressing M-RET, move the selection up to the input prompt by pressing the up arrow key and then press RET.

In order to configure Vertico and other packages in your init.el, you may want to take advantage of use-package. Here is an example configuration:

;; Enable vertico
(use-package vertico
  :custom
  ;; (vertico-scroll-margin 0) ;; Different scroll margin
  ;; (vertico-count 20) ;; Show more candidates
  ;; (vertico-resize t) ;; Grow and shrink the Vertico minibuffer
  ;; (vertico-cycle t) ;; Enable cycling for `vertico-next/previous'
  :init
  (vertico-mode))

;; Persist history over Emacs restarts. Vertico sorts by history position.
(use-package savehist
  :init
  (savehist-mode))

;; A few more useful configurations...
(use-package emacs
  :custom
  ;; Support opening new minibuffers from inside existing minibuffers.
  (enable-recursive-minibuffers t)
  ;; Hide commands in M-x which do not work in the current mode.  Vertico
  ;; commands are hidden in normal buffers. This setting is useful beyond
  ;; Vertico.
  (read-extended-command-predicate #'command-completion-default-include-p)
  :init
  ;; Add prompt indicator to `completing-read-multiple'.
  ;; We display [CRM<separator>], e.g., [CRM,] if the separator is a comma.
  (defun crm-indicator (args)
    (cons (format "[CRM%s] %s"
		  (replace-regexp-in-string
		   "\\`\\[.*?]\\*\\|\\[.*?]\\*\\'" ""
		   crm-separator)
		  (car args))
	  (cdr args)))
  (advice-add #'completing-read-multiple :filter-args #'crm-indicator)

  ;; Do not allow the cursor in the minibuffer prompt
  (setq minibuffer-prompt-properties
	'(read-only t cursor-intangible t face minibuffer-prompt))
  (add-hook 'minibuffer-setup-hook #'cursor-intangible-mode))

I recommend to give Orderless completion a try, which is more flexible and powerful than the default completion styles.

;; Optionally use the `orderless' completion style.
(use-package orderless
  :custom
  ;; Configure a custom style dispatcher (see the Consult wiki)
  ;; (orderless-style-dispatchers '(+orderless-consult-dispatch orderless-affix-dispatch))
  ;; (orderless-component-separator #'orderless-escapable-split-on-space)
  (completion-styles '(orderless basic))
  (completion-category-defaults nil)
  (completion-category-overrides '((file (styles partial-completion)))))

The basic completion style is specified as fallback in addition to orderless in order to ensure that completion commands which rely on dynamic completion tables, e.g., completion-table-dynamic or completion-table-in-turn, work correctly. See the Consult wiki for my advanced Orderless configuration with style dispatchers. Additionally enable partial-completion for file path expansion. partial-completion is important for file wildcard support in find-file. In order to open multiple files with a wildcard at once, you have to submit the prompt with M-RET. Alternative first move to the prompt and then press RET.

See also the Vertico Wiki for additional configuration tips. For more general documentation read the chapter about completion in the Emacs manual. If you want to create your own completion commands, you can find documentation about completion in the Elisp manual.

We maintain small extension packages to Vertico in this repository in the subdirectory extensions/. The extensions are installed together with Vertico if you pull the package from ELPA. The extensions are inactive by default and can be enabled manually if desired. Furthermore it is possible to install all of the files separately, both vertico.el and the vertico-*.el extensions. Currently the following extensions come with the Vertico ELPA package:

• vertico-buffer: vertico-buffer-mode to display Vertico like a regular buffer.
• vertico-directory: Commands for Ido-like directory navigation.
• vertico-flat: vertico-flat-mode to enable a flat, horizontal display.
• vertico-grid: vertico-grid-mode to enable a grid display.
• vertico-indexed: vertico-indexed-mode to select indexed candidates with prefix arguments.
• vertico-mouse: vertico-mouse-mode to support for scrolling and candidate selection.
• vertico-multiform: Configure Vertico modes per command or completion category.
• vertico-quick: Commands to select using Avy-style quick keys.
• vertico-repeat: The command vertico-repeat repeats the last completion session.
• vertico-reverse: vertico-reverse-mode to reverse the display.
• vertico-suspend: The command vertico-suspend suspends and restores the current session.
• vertico-unobtrusive: vertico-unobtrusive-mode displays only the topmost candidate.

See the commentary of those files for configuration details. With these extensions it is possible to adapt Vertico such that it matches your preference or behaves similar to other familiar UIs. For example, the combination vertico-flat plus vertico-directory resembles Ido in look and feel. For an interface similar to Helm, the extension vertico-buffer allows you to configure freely where the completion buffer opens, instead of growing the minibuffer. Furthermore vertico-buffer will adjust the number of displayed candidates according to the buffer height.

Configuration example for vertico-directory:

;; Configure directory extension.
(use-package vertico-directory
  :after vertico
  :ensure nil
  ;; More convenient directory navigation commands
  :bind (:map vertico-map
	      ("RET" . vertico-directory-enter)
	      ("DEL" . vertico-directory-delete-char)
	      ("M-DEL" . vertico-directory-delete-word))
  ;; Tidy shadowed file names
  :hook (rfn-eshadow-update-overlay . vertico-directory-tidy))

Vertico integrates well with complementary packages, which enrich the completion UI. These packages are fully supported:

• Marginalia: Rich annotations in the minibuffer
• Consult: Useful search and navigation commands
• Embark: Minibuffer actions and context menu
• Orderless: Advanced completion style

In order to get accustomed with the package ecosystem, I recommend the following quick start approach:

1. Start with plain Emacs (emacs -Q).
2. Install and enable Vertico to get incremental minibuffer completion.
3. Install Orderless and/or configure the built-in completion styles for more flexible minibuffer filtering.
4. Install Marginalia if you like rich minibuffer annotations.
5. Install Embark and add two keybindings for embark-dwim and embark-act. I am using the mnemonic keybindings M-. and C-. since these commands allow you to act on the object at point or in the minibuffer.
6. Install Consult if you want additional featureful completion commands, e.g., the buffer switcher consult-buffer with preview or the line-based search consult-line.
7. Install Embark-Consult and Wgrep for export from consult-line to occur-mode buffers and from consult-grep to editable grep-mode buffers.
8. Fine tune Vertico with extensions.

The ecosystem is modular. You don't have to use all of these components. Use only the ones you like and the ones which fit well into your setup. The steps 1. to 4. introduce no new commands over plain Emacs. Step 5. introduces the new commands embark-act and embark-dwim. In step 6. you get the Consult commands, some offer new functionality not present in Emacs already (e.g., consult-line) and some are substitutes (e.g., consult-buffer for switch-to-buffer).

An often requested feature is the ability to display the completions in a child frame popup. Personally I am critical of using child frames for minibuffer completion. From my experience it introduces more problems than it solves. Most importantly child frames hide the content of the underlying buffer. Furthermore child frames do not play well together with changing windows and entering recursive minibuffer sessions. On top, child frames can feel slow and sometimes flicker. A better alternative is the vertico-buffer display which can even be configured individually per command using vertico-multiform. On the plus side of child frames, the completion display appears at the center of the screen, where your eyes are focused. Please give the following packages a try and judge for yourself.

• mini-frame: Display the entire minibuffer in a child frame.
• mini-popup: Slightly simpler alternative to mini-frame.
• vertico-posframe: Display only the Vertico minibuffer in a child frame using the posframe library.

There are many alternative completion UIs, each UI with its own advantages and disadvantages.

Vertico aims to be 100% compliant with all Emacs commands and achieves that with a minimal code base, relying purely on completing-read while avoiding to invent its own APIs. Inventing a custom API as Helm or Ivy is explicitly avoided in order to increase flexibility and package reuse. Due to its small code base and reuse of the Emacs built-in facilities, bugs and compatibility issues are less likely to occur in comparison to completion UIs or monolithic completion systems.

Since Vertico only provides the UI, you may want to combine it with some of the complementary packages, to give a full-featured completion experience similar to Helm or Ivy. The idea is to have smaller independent components, which one can add and understand step by step. Each component focuses on its niche and tries to be as non-intrusive as possible. Vertico targets users interested in crafting their Emacs precisely to their liking - completion plays an integral part in how the users interacts with Emacs.

There are other interactive completion UIs, which follow a similar philosophy:

• Mct: Minibuffer and Completions in Tandem. Mct reuses the default *Completions* buffer and enhances it with automatic updates and additional keybindings, to select a candidate and move between minibuffer and completions buffer. Since Mct uses a fully functional buffer you can use familiar buffer commands inside the completions buffer. The main distinction to Vertico's approach is that *Completions* buffer displays all matching candidates. This has the advantage that you can interact freely with the candidates and jump around with Isearch or Avy. On the other hand it necessarily causes a slowdown.
• Selectrum: Selectrum is the predecessor of Vertico has been deprecated in favor of Vertico. Read the migration guide when migrating from Selectrum. Vertico was designed specifically to address the technical shortcomings of Selectrum. Selectrum is not fully compatible with every Emacs completion command and dynamic completion tables, since it uses its own filtering infrastructure, which deviates from the standard Emacs completion facilities.
• Icomplete: Emacs comes with the builtin icomplete-vertical-mode, which is a more bare-bone than Vertico. Vertico offers additional flexibility thanks to its extensions.

If you want to learn more about Vertico and minibuffer completion, check out the following resources:

• Configurations which use Vertico and Corfu for completion:
  • Doom Emacs Vertico Module
  • Crafted Emacs Completion Module
  • Prot's Emacs configuration
• Videos:
  • Emacs Completion Explained (2022-07-19) by Andrew Tropin.
  • Emacs Minibuffer Completions (2022-02-12) by Greg Yut.
  • Vertico Extensions for Emacs (2022-01-08) by Karthik Chikmagalur.
  • Using Emacs Episode 80 - Vertico, Marginalia, Consult and Embark (2021-10-26) by Mike Zamansky.
  • System Crafters Live! - Replacing Ivy and Counsel with Vertico and Consult (2021-05-21) by David Wilson.
  • Streamline Your Emacs Completions with Vertico (2021-05-17) by David Wilson.
  • Modern Emacs: all those new tools that make Emacs better and faster (2024-03-06) by Marie-Hélène Burle.

Since this package is part of GNU ELPA contributions require a copyright assignment to the FSF.

When you observe an error in the vertico--exhibit post command hook, you should install an advice to enforce debugging. This allows you to obtain a stack trace in order to narrow down the location of the error. The reason is that post command hooks are automatically disabled (and not debugged) by Emacs. Otherwise Emacs would become unusable, given that the hooks are executed after every command.

(setq debug-on-error t)

(defun force-debug (func &rest args)
  (condition-case e
      (apply func args)
    ((debug error) (signal (car e) (cdr e)))))

(advice-add #'vertico--exhibit :around #'force-debug)

Vertico is robust in most scenarios. However some completion commands make certain assumptions about the completion styles and the completion UI. Some of these assumptions may not hold in Vertico or other UIs and require minor workarounds.