:completion vertico

• @hlissner
• @iyefrat

Become a maintainer?

+icons#

Adds icons to file and buffer category completion selections.

• all-the-icons-completion if +icons
• consult
• consult-flycheck if :checkers syntax
• embark
• embark-consult
• marginalia
• orderless
• vertico
• wgrep

No hacks documented for this module.

When in an active Vertico completion session, the following doom added keybindings are available:

embark-act will prompt you with a which-key menu with useful commands on the selected candidate or candidate list, depending on the completion category. Note that you can press C-h instead of choosing a command to filter through the options with a Vertico buffer, that also has slightly more detailed descriptions due to Marginalia annotations.

This module provides an interface to navigate within a project using projectile:

This module provides interactive text search and replace using ripgrep.

Prefixing these keys with the universal argument (SPC u for evil users; C-u otherwise) changes the behavior of these commands, instructing the underlying search engine to include ignored files.

This module also provides Ex Commands for evil users:

The optional bang (!) is equivalent to the universal argument for the previous commands.

On top of the usual Vertico keybindings, search commands also offer support for exporting the current candidate list to an editable buffer C-c C-e. After editing the changes can be committed with C-c C-c and aborted with C-c C-k (alternatively ZZ and ZQ, for evil users). It uses wgrep for grep searches, wdired for file searches, and occur for buffer searches.

This module provides some in buffer searching bindings:

• <leader> s s (isearch)
• <leader> s S (+vertico/search-symbol-at-point via consult-line)
• <leader> s b (consult-line)

An occur-edit buffer can be opened from consult-line with C-c C-e.

Marginalia annotations for symbols (e.g. SPC h f and SPC h v) come with extra information the nature of the symbol. For the meaning of the annotations see marginalia--symbol-class.

When using orderless to filter through candidates, the default behaviour is for each space separated input to match the candidate as a regular expression or literally.

Note that due to this style of matching, pressing tab does not expand the input to the longest matching prefix (like shell completion), but rather uses the first matched candidate as input. Filtering further is instead achieved by pressing space and entering another input. In essence, when trying to match foobar.org, instead of option 1., use option 2.:

1. (BAD) Enter foo TAB, completes to foobar., enter org RET
2. (GOOD) Enter foo SPC org RET

Doom has some builtin style dispatchers for more finegrained filtering, which you can use to further specify each space separated input in the following ways:

Vertico provides several extentions that can be used to extend it’s interface

Much of the behaviour of Consult commands can be changed with consult-customize. This module already does this, if you want to override the module’s modifications, do:

(setq consult--read-config nil)
(consult-customize
;...
)

If you are changing the preview key (set to C-SPC), remember to change the binding on vertico-map as well, as the binding there gets previews to work to an extent on non-consult commands as well.

You can add more Marginalia annotation levels and change the existing ones by editing marginalia-annotator-registry

You can change the available commands in Embark for category $cat by editing embark-$cat-map, and even add new categories. Note that you add categories by defining them through marginalia, and embark picks up on them.