Migrating from Selectrum to Vertico

Migrating from Selectrum to Vertico

Both Selectrum and Vertico are completion user interfaces that, by default, present candidates as vertical columns in the minibuffer.

During the development of Selectrum, it became clear that Selectrum does not closely enough follow the Emacs completion APIs, which leads to problems in certain cases. Selectrum uses its own filtering pipeline which deviates from the builtin Emacs mechanism using completion styles. This can be seen in the Selectrum issue tracker, especially regarding dynamic completion tables (instead of just lists of candidates), which are widespread throughout the Emacs code base but unsupported by Selectrum. Examples of dynamic completion tables include completion-table-dynamic, completion-table-in-turn, completing-read-multiple, and completion-file-name-table, which underlies find-file.

Vertico began as a prototype in fixing the support of dynamic completion tables in Selectrum. However, in the end, it turned out to be easier to package up the prototype as a new package instead of fixing Selectrum, which would have grown further in complexity and size. In many ways, Vertico works like the built-in Icomplete. It is by design meant to work better and focuses on compatibility with all Emacs completion commands.

Against this backdrop, there is a current issue where the deprecation of Selectrum in favor of Vertico is discussed. This document tries to describe things of interest when moving from Selectrum to Vertico.

Loading Vertico Extensions

Some Vertico features are written as extensions. These extensions are installed automatically via package.el as part of the package from GNU ELPA. When Vertico is installed via straight.el, straight must be told explicitly about this extension directory:

(use-package vertico
  :straight (:files (:defaults "extensions/*"))
  :init
  (vertico-mode))

The individual extensions specify autoloads for the exposed commands, such that they can be used directly.

Sorting and Filtering

Using prescient.el in Vertico

The package vertico-prescient exists to integrate prescient.el with Vertico and is available from MELPA. It is the Vertico version of selectrum-prescient, company-prescient, and the other prescient.el integration packages.

Instructions for setting up prescient.el for Vertico are given on another page in the Vertico wiki.

Completion Styles

Selectrum (by default) and Vertico use completion styles. See the variable completion-styles.

Faces

Here we list the counterparts of the faces used in Vertico and Selectrum. For annotations, Vertico just uses the built-in completion faces. The faces vertico-quick, vertico-indexed, and vertico-mouse are defined by their respective extensions.

Selectrum	Vertico
selectrum-completion-annotation	completions-annotations
selectrum-completion-docsig	completions-annotations
selectrum-current-candidate	vertico-current
selectrum-group-separator	vertico-group-separator
selectrum-group-title	vertico-group-title
selectrum-mouse-highlight	vertico-mouse
selectrum-quick-keys-highlight	vertico-quick1
selectrum-quick-keys-match	vertico-quick2
minibuffer-prompt	vertico-indexed

Repeating Completion Sessions

To replace the command selectrum-repeat, see the Vertico extension vertico-repeat.el.

(global-set-key "\M-R" #'vertico-repeat)
(add-hook 'minibuffer-setup-hook #'vertico-repeat-save)
;; (with-eval-after-load 'savehist
;;   (add-to-list 'savehist-additional-variables 'vertico-repeat-history))

Quick Selection and Key Bindings

For the related faces, see the section Faces.

To replace the user option selectrum-show-indices, see the extension vertico-indexed.el. Enabling vertico-indexed-mode will advise the commands vertico-insert, vertico-exit, and vertico-directory-enter to accept numeric prefix arguments. By default, Vertico starts indexing at 0, while Selectrum starts at 1.

(vertico-indexed-mode 1)
(setq vertico-index-start 1)

To replace the commands selectrum-quick-select and selectrum-quick-insert, use the extension vertico-quick.el.

;; Note: No separate mode.  This extension only defines commands.
(define-key vertico-map (kbd "M-i") #'vertico-quick-insert)
(define-key vertico-map (kbd "M-m") #'vertico-quick-exit)

Other user options are:

Selectrum	Vertico
selectrum-cycle-movement	vertico-cycle

Mouse Use

Selectrum enables using the mouse to select candidates by default. In Vertico, that is done by the extension vertico-mouse.el. The bindings are the same: left click for selection, right click for insertion.

(vertico-mouse-mode 1)

You might need to disable context-menu-mode to use these commands, as it has a higher priority than the keymap of the propertized candidates.

Handling Directories Specially

There is no equivalent of selectrum-files-select-input-dirs.

The extension vertico-directory.el provides commands for better editing directories on the input line. While Selectrum provides a command to delete directories or sexps, the closest Vertico command deletes directories or words.

NOTE: In Selectrum, selectrum-backward-kill-sexp will always delete back to the previous directory separator. The Vertico command matches the Ido behavior. It will only trigger when point is immediately after the directory separator.

(define-key vertico-map (kbd "M-<DEL>") #'vertico-directory-delete-word)

Formatting, Candidate Display, and Window Configuration

The following configuration variables have direct correspondences in both UIs.

Selectrum	Vertico
selectrum-fix-vertical-window-height	vertico-resize
selectrum-max-window-height	vertico-count

Selectrum	Vertico
selectrum-multiline-display-settings	vertico-multiline

Selectrum	Vertico
selectrum-count-style	vertico-count-format
selectrum-show-indices	vertico-indexed-mode

Display Styles

To replace selectrum-display-styles, see extensions like Vertico Flat, Vertico Grid, Vertico Reverse, and Vertico Unobtrusive.

;; Enabling Vertico Flat.
(vertico-flat-mode 1)

There is no command like selectrum-cycle-display-style, but individual styles can be toggled using the flexible extension vertico-multiform.el, as shown in the Vertico manual.

;; Using the Vertico Multiform commands.
(vertico-multiform-mode 1)
(define-key vertico-map "\M-V" #'vertico-multiform-vertical)
(define-key vertico-map "\M-G" #'vertico-multiform-grid)
(define-key vertico-map "\M-F" #'vertico-multiform-flat)
(define-key vertico-map "\M-R" #'vertico-multiform-reverse)
(define-key vertico-map "\M-U" #'vertico-multiform-unobtrusive)

Displaying Candidates Outside of the Minibuffer

To display candidates outside of the minibuffer, use the extension vertico-buffer.el.

;; Enable buffer display
(vertico-buffer-mode 1)

Selectrum	Vertico
selectrum-display-action	vertico-buffer-display-action