Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 38 ยท Packages and Programming Modes

Minibuffer Completion: Vertico, Orderless, Marginalia and Consult

Understand Emacs completion styles and the modern stack of Vertico, Orderless, Marginalia, Consult and Embark, with a configuration you can paste in.

Every time Emacs asks you for something (a command after M-x, a file after C-x C-f, a buffer after C-x b) it uses the minibuffer and a completion system. Out of the box this works, but it shows candidates only after you press TAB or ?. A handful of small packages make it feel like a modern command palette: a vertical list of candidates, fuzzy matching, helpful annotations and searchable results. This lesson explains how completion works and how to assemble that stack.

The Elisp snippets are real configuration. The runnable blocks are JavaScript stand-ins that model matching and ranking so you can see how the styles differ.

How completion works

Emacs separates two ideas:

  • The frontend decides how candidates are displayed and chosen (the default minibuffer, Vertico, Ivy, Helm...).
  • The completion style decides which candidates match what you typed. The variable completion-styles lists styles to try in order. Built-in ones include basic (prefix match), partial-completion (f-b matches foo-bar; ~/.e/i can expand directories), substring, and flex (typed characters appear in order anywhere: fbr matches foo-bar).

Any command that calls completing-read benefits from improvements to either layer, which is why the modern approach is to replace parts independently ("small, composable packages") rather than adopt one large framework.

JS Stand-in: prefix, substring and flex styles

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The modern stack

Vertico

Vertico (by Daniel Mendler) shows candidates in a vertical list under the prompt, and builds on the standard completion machinery, so it works with every command. Move with C-n/C-p, accept with RET.

ELISP
(use-package vertico
  :ensure t
  :init (vertico-mode 1)
  :custom (vertico-cycle t))

Orderless

Orderless is a completion style: you type space-separated components, and a candidate matches when it matches all of them, in any order. buf kill finds kill-buffer; file find finds find-file. Each component can be matched literally, as a regexp, as initials or with flex matching.

ELISP
(use-package orderless
  :ensure t
  :custom
  (completion-styles '(orderless basic))
  (completion-category-overrides '((file (styles basic partial-completion)))))

The completion-category-overrides line keeps file name completion using partial-completion so that paths still expand the way you expect.

JS Stand-in: orderless matching

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Marginalia

Marginalia adds annotations beside each candidate: the docstring and key binding for commands, file sizes and dates, the mode of a buffer. It changes nothing about matching.

ELISP
(use-package marginalia
  :ensure t
  :init (marginalia-mode 1))

Consult

Consult provides improved versions of everyday commands that use completing-read, often with live previews:

Command What it does
consult-buffer Switch buffer, recent file, bookmark or project in one list
consult-line Search the current buffer, jump with preview
consult-ripgrep Live project search through ripgrep (needs rg)
consult-imenu Jump to a function or heading
consult-yank-pop Browse the kill ring
consult-goto-line Go to a line with a preview
ELISP
(use-package consult
  :ensure t
  :bind (("C-x b" . consult-buffer)
         ("M-y"   . consult-yank-pop)
         ("M-g g" . consult-goto-line)
         ("M-s l" . consult-line)
         ("M-s r" . consult-ripgrep)))

Embark

Embark gives you a contextual menu for the thing at point or the current candidate: bound to C-. (act), it lists actions such as "delete file", "open in other window" or "copy URL" depending on what the item is. It can also collect candidates into a regular buffer you can edit. Bind it with (global-set-key (kbd "C-.") #'embark-act) and install embark-consult for integration.

In-buffer completion: Corfu

Vertico covers the minibuffer. Corfu does the same for completion while typing in a buffer (popup of symbols), a lighter alternative to Company. See completion, snippets and diagnostics.

Useful built-in settings

Several settings improve the default minibuffer even without packages:

ELISP
(setq enable-recursive-minibuffers t)   ; allow minibuffer use inside the minibuffer
(setq read-extended-command-predicate #'command-completion-default-include-p)
(savehist-mode 1)                       ; remember minibuffer history across sessions
(setq completion-ignore-case t
      read-buffer-completion-ignore-case t
      read-file-name-completion-ignore-case t)

savehist-mode also lets Vertico rank your most recent choices first.

The stack is modular: you can try Vertico alone, add Orderless next week, then Marginalia. Each piece stays useful on its own, and none of them replaces how Emacs completes; they plug into it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a completion style decide?

    Styles define matching (prefix, substring, flex, orderless). Frontends like Vertico decide the display.
  2. 2. With Orderless, which input finds kill-buffer?

    Each space-separated component only needs to match somewhere, in any order.
  3. 3. Which package adds annotations such as docstrings next to candidates?

    Marginalia annotates candidates; the others handle display, matching and commands.
  4. 4. What is consult-line used for?

    consult-line searches the current buffer and previews the match while you move.

Summary

  • A frontend displays candidates; a completion style decides what matches.
  • Vertico gives the vertical list, Orderless the any-order matching, Marginalia the annotations, Consult the better commands, Embark the context actions.
  • Keep file completion on partial-completion via completion-category-overrides.
  • Enable savehist-mode so recent choices rank first.
  • Add one piece at a time; each is useful alone.

Next: Programming Modes, Eglot and Tree-sitter