marginalia.el: colour annotations on minibuffer completions

It annotates candidates, and never changes them

The package provides marginalia-mode, which adds marginalia to minibuffer completions. Marginalia are marks or annotations placed at the margin of the page of a book, and here they are helpful colourful annotations placed at the margin of the minibuffer for the completion candidates. The limitation is stated just as precisely, and it is the right one. Marginalia can only add annotations to the completion candidates, and it cannot modify the appearance of the candidates themselves, which are shown unaltered as supplied by the original command. That constraint is what keeps the package compatible with everything else in the completion ecosystem. It does not take over the minibuffer, it does not replace the completion UI, and it does not decide what you see, it only adds a column of information next to what somebody else decided you should see. The two authors are Omar Antolín Camarena and Daniel Mendler, and the package is available from ELPA and from MELPA.

The completion category picks the annotation

Annotations are added based on the completion category. The example the documentation gives is that find-file reports the file category and M-x reports the command category, and each category has an annotator that knows what is worth saying about that kind of candidate. The annotator is a function that takes a completion candidate string as an argument and returns an annotation string to be displayed after the candidate in the minibuffer. You can cycle between more or less detailed annotators, or turn the annotator off entirely, with the command marginalia-cycle. In the recommended configuration that command is bound locally in the minibuffer to M-A, and the comment in the configuration file explains the subtlety that the binding has to be made available in the Completions buffer too, which means adding it to completion-list-mode-map as well. The information itself is often quite compact but genuinely useful: the annotations for Elisp symbols include the symbol class, v for a variable, f for a function, c for a command, and the docstring of marginalia--symbol-class explains what the classifications mean.

The classifier layer for commands that do not report a category

Here is the problem the package has to solve, and the solution is the most interesting part of the design. Commands that support minibuffer completion use a completion table of all the available candidates, and the candidates are associated with a category such as command, file, face or variable depending on what they are. But not all commands, including some of the built in ones, specify the category of their candidates. To compensate, Marginalia hooks into the Emacs completion framework and runs the classifiers listed in the variable marginalia-classifiers, which use the command's prompt or other properties of the candidates to work out the category. One classifier is marginalia-classify-by-prompt, which checks the minibuffer prompt against the regexps in the marginalia-prompt-categories alist. The documentation shows the shape of that alist, where a regexp is paired with a category:

  (add-to-list 'marginalia-prompt-categories '("\\<face\\>" . face))

The second classifier, marginalia-classify-by-command-name, uses the marginalia-command-categories alist to set the category from the command name, and the documentation notes it is particularly useful when the prompt classifier yields a false positive, which is the failure mode you would expect from matching on free text.

Installing it and pairing it with the rest of your setup

The package is available from ELPA or MELPA and you install it with package-install. The documentation recommends using it with either Vertico, Mct, Icomplete or the default completion UI, so Marginalia is a decoration layer that works on top of a completion engine rather than a replacement for one. It can also be combined with Embark for action support and with Consult, which provides many useful commands. The configuration is short, and the comments in it carry the rules that matter: Marginalia has to be activated in the init section of use-package so that the mode is enabled right away, and the note in the file says that this forces loading the package, which is the cost of enabling it globally rather than lazily.

(use-package marginalia
  :bind (:map minibuffer-local-map
         ("M-A" . marginalia-cycle))
  :init
  (marginalia-mode))

The readme is written as Org mode, with the Texinfo export settings at the top and a table of contents, and the file is the only source file in the repository alongside a README.org, a NEWS.org and a .elpaignore for the package archive.

Package authors are told not to depend on it

This is the most unusual thing in the documentation, and it deserves attention from anyone who writes Emacs packages. The intention of the Marginalia package is to give the user means to overwrite completion categories and to add custom annotators for existing commands in their user configuration, and Marginalia is a user facing package and is not intended to be used as a library. It therefore does not expose library functions as part of its public API. The advice to package authors is concrete: if you add your own completion commands to your package, specify an annotation-function or an affixation-function, which are documented in the Elisp manual, and that avoids a dependency on Marginalia entirely. If you use consult--read, you can specify an :annotate keyword argument instead. There is one documented exception, and it is a good one. If you want to implement annotations for an existing package, hypothetic.el, which has no annotations and where they cannot be added, then creating a marginalia-hypothetic.el package is a good idea, because Marginalia provides the facilities to enhance existing commands from the outside. The design is a deliberate boundary between a user facing mode and a library, which is unusual and welcome.

Why the classifiers matter to Embark

Completion categories are not only for Marginalia's own annotations. They are also what Embark uses, since Embark associates actions based on the completion category, and the documentation says that Embark benefits from Marginalia's classifiers. That is a neat piece of leverage: a user who has installed Marginalia gets better categories for Embark for free, and a user who wants better Embark actions gets them by installing a package that seems to be about colours. The same alists serve both, which means the marginalia-prompt-categories and marginalia-command-categories variables are the place to look when an action does not appear where you expect it. The annotators themselves are looked up in the marginalia-annotators alist, and the documentation suggests starting there to learn what the different annotations mean, then reading the annotation function for the category you are interested in. The repository is licensed under the GPL-3.0, publishes no GitHub releases, and the last push was on 2026-10-10.

Editorial conclusion

Marginalia is worth installing if you spend time in the minibuffer, because the annotations turn a list of identical looking candidates into a list you can read, and the package is small enough to read in an evening. It is the wrong tool if you are looking for a completion engine, since it only annotates what another package produced, and it is the wrong dependency for a package you maintain, because the readme asks you not to take one. Before you install, look at marginalia-annotators to see what the annotations mean, and if you use Embark or Consult, check the interaction, since the classifiers that Marginalia supplies are exactly what Embark uses to decide which actions to offer.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. minad/marginalia on GitHub
4. README