-
-
Notifications
You must be signed in to change notification settings - Fork 64
Migrating from Selectrum to Vertico
Both Selectrum and Vertico are completion user interfaces that, by default, present candidates as vertical columns in the minibuffer.
As Selectrum was developed, it became clear that for certain cases, Selectrum did not closely enough mimic how Emacs’s default completion UI worked. This can be seen in Selectrum’s issue tracker especially regarding text properties (sometimes returned, sometimes not) [fn:1] and dynamic candidate-producing functions (instead of just lists of candidates) [fn:2]. Many of these issues have been fixed, but not all.
Vertico began as an experiment in fixing the support of dynamic completion tables[fn:3] in Selectrum.[fn:4] However, it turned out to be easier to just make a new package that more closely complied with Emacs’s expectations. In many ways, Vertico’s implementation works like that of the built-in Icomplete.[fn:5] It is by design meant to work better.
There is a current investigation into whether it is reasonable to deprecate Selectrum in Vertico, given the above.[fn:6] This document tries to describe things of interest when moving from Selectrum to Vertico.
- Loading Vertico’s Extensions
- Sorting and Filtering
- Faces
- Repeating Completion Sessions
- Quick Selection and Key Bindings
- Handling Directories Specially
- Formatting, Candidate Display, and Window Configuration
- Footnotes
Some features that are in base Selectrum are written as extensions in Vertico.
These extensions are already in the load-path when installed via package.el.
When Vertico is installed via straight.el, the directory containing these
packages must be added to load-path manually.
(let* ((vertico-dir (file-name-directory (locate-library "vertico.el")))
(extension-dir (expand-file-name "extensions" vertico-dir)))
(add-to-list 'load-path extension-dir))The individual extensions should be require-ed after Vertico is loaded, such
as with with-eval-after-load.
As of recently, using prescient.el for sorting and filtering both work in
Vertico. The only kink is that advice is required to make prescient.el
remember the chosen candidate. There is currently no hook that can run
prescient-remember.
Currently, there is no vertico-prescient package as there is for Selectrum and
Company. Instead, instructions for setting up prescient.el for Vertico is
given on another page in the Vertico wiki.
Selectrum (by default) and Vertico uses Emacs’s completion styles. See the
variable completion-styles.
Vertico does not have a direct counterpart for all of Selectrum’s faces.
For some things, it just uses Emacs’s built-in completion faces.
Some of these faces are only available after loading the extension,
such as the faces vertico-quick1 and vertico-quick2 from Vertico Quick.
| 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 |
None. Uses minibuffer-prompt. |
vertico-indexed |
To replace the command selectrum-repeat, see the Vertico extension Vertico
Repeat.
(require 'vertico-repeat)
(define-key mode-specific-map "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))For the related faces, see the section Faces.
To replace the user option selectrum-show-indices, see the extension Vertico
Indexed. 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.
(require 'vertico-indexed)
(vertico-indexed-mode 1)
(setq vertico-index-start 1) ; Available in development version.To replace the commands selectrum-quick-select and selectrum-quick-insert,
use the extension Vertico Quick.
;; Note: No mode to enable. This extension only defines commands.
(require 'vertico-quick)
(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 |
Selectrum enables using the mouse to select candidates by default. In Vertico, that is done by the extension Vertico Mouse. The bindings are the same: left click for selection, right click for insertion.
(require 'vertico-mouse)
(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.
There is no equivalent of selectrum-files-select-input-dirs.
The extension Vertico Directory provides commands for better editing directories on the input line. While Selectrum provides a command to delete directories or sexps, the closest Vertico command is one that deletes directories or words.
(require 'vertico-directory)
;; NOTE: A PR is open to add this command to the extension.
(defun my-vertico-directory-delete-sexp (&optional n)
"Delete N directories or sexps before point."
(interactive "p")
(unless (vertico-directory-up n)
(let ((pt (point)))
(backward-sexp n)
(delete-region pt (point)))))
(define-key vertico-map (kbd "C-M-DEL") #'my-vertico-directory-delete-sexp)
(define-key vertico-map (kbd "C-M-<backspace>") #'my-vertico-directory-delete-sexp)| Selectrum | Vertico |
|---|---|
| selectrum-fix-vertical-window-height | vertico-resize |
| selectrum-max-window-height | vertico-count |
| selectrum-multiline-display-settings | vertico-multiline |
| Selectrum | Vertico |
| selectrum-count-style | vertico-count-format |
| selectrum-show-indices | See Vertico Indexed above. |
To replace selectrum-display-styles, see extensions like Vertico Flat, Vertico
Grid, Vertico Unobtrusive.
(require 'vertico-flat)
(vertico-flat-mode 1)There is no command like selectrum-cycle-display-style, but individual styles
can be cycled using the extension Vertico Multiform, as shown in the Vertico
readme.
(require 'vertico-multiform)
(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)To display candidates outside of the minibuffer, use the extension Vertico
Buffer. Where the buffer is displayed is configured using
vertico-buffer-display-action, Vertico’s version of
selectrum-display-action.
(require 'vertico-buffer)
(vertico-buffer-mode 1)[fn:1] https://github.com/radian-software/selectrum/issues/180#issuecomment-675390429
[fn:2] https://github.com/radian-software/selectrum/issues/114
[fn:3] “Dynamic” means that candidates are produced based on user input. One
example of dynamic completion is the package AMX, which includes command
bindings in the candidate itself (not as annotations) but can still fallback and
match a plain command name by using completion-table-in-turn. This came up in
https://github.com/radian-software/selectrum/issues/211.
[fn:4] https://github.com/radian-software/selectrum/issues/598#issuecomment-1121682815
[fn:5] https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html
See also the Consult Wiki, the Embark Wiki and the Corfu Wiki!