# Selectrum: the Emacs completion UI that told you to use Vertico

> A completion front end for Emacs built on standard Emacs APIs, which now exists mostly as a set of instructions for migrating away from it. The package's own readme opens by announcing its own replacement, and the development work has moved to Vertico.

**radian-software/selectrum** — 🔔 Better solution for incremental narrowing in Emacs.

- Repository: https://github.com/radian-software/selectrum
- Stars: 724 · Forks: 31
- Language: Emacs Lisp
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/radian-software-selectrum

## The readme starts by announcing its own replacement

The most important thing to know about Selectrum is stated on line one of its readme, under a heading that reads Selectrum... is replaced.

Selectrum has been replaced by Vertico, a package which provides essentially the same features in a simpler way, and integrates more effectively with other packages. The original author of Selectrum, @raxod502, now uses Vertico instead in their Emacs configuration, Radian.

That is an unusual thing for a project's own documentation to say, and it changes what the project is. This is not a package in active competition with its successors. It is a package that has been deliberately handed over, with the maintainers directing readers toward the replacement and toward a migration guide.

There is a migration guide to migrate from Selectrum to Vertico, hosted in the Vertico wiki, and the team says that over time they will improve this guide and ensure that it is possible to achieve feature parity for all existing configurations of Selectrum in the Vertico ecosystem, possibly with the use of one or more Vertico extension packages, of which there are many already.

Their reasoning is stated plainly: it's always annoying to change from one thing to another, but the replacement will be a benefit to everyone pretty soon, because Vertico is a lot simpler and easier to maintain and integrate, meaning the end result is likely to be more robust and likely to stick around for longer.

## What Selectrum was built to be, before the handover

The original positioning is still described in the readme, and it explains why the project was worth handing over carefully rather than deleting.

Selectrum aims to provide a better completion UI using standard Emacs APIs. In essence it is an interface for selecting items from a list. And the pitch, in the project's own framing, is that Selectrum is a better solution for incremental narrowing in Emacs, replacing Helm, Ivy and Ido.

The emphasis on standard Emacs APIs is the architectural commitment. The focus of Selectrum is on providing an enhanced completion UI and compose with other packages which stay within the constraints of the standard Emacs API. Because of the modular approach there are several possible package combinations, and setup help for integration with other packages lives in the project wiki.

The list of things it would handle covers most of the completion surfaces a user touches. You can use it to run a command with M-x, to open a file with C-x C-f, which is find-file, to switch buffers, and it is noted that even TRAMP works great out of the box, which the project illustrates with a screenshot of using sudo via TRAMP. And every other command in Emacs is automatically enhanced, without the need for any configuration, including finding libraries with load-path shadows.

That last claim is the one that mattered most in practice. A completion UI that requires per-command setup is a completion UI nobody finishes configuring.

## Installing and enabling it, which is two lines of Lisp

The installation is on MELPA, and the recommended route is straight.el, which is itself a package from the same organisation:

```elisp
(straight-use-package 'selectrum)
```

The readme notes that you may install using any other package manager if you prefer. There is a MELPA Stable badge as well as the MELPA one, which matters for a package that has not had a tagged release in years, because the stable channel is where a frozen package stays available.

Enabling it is one form:

```elisp
(selectrum-mode +1)
```

That goes in your init-file, and the effect is that now all completion commands will automatically use Selectrum. The single global mode is the whole integration. There is no per-command setup, no keymap to learn for basic use, and no advice to attach.

The developer guide in the readme is where the internals are documented: usage of Selectrum, sorting filtering and highlighting, text properties, hooks and variables. That is the section to read if you are writing an extension against it rather than configuring it.

The repository layout backs this up. There is a single selectrum.el at the root, a test directory, a Makefile, a Dockerfile, scripts for the linting helpers, an images directory for the screenshots the readme uses, and a CHANGELOG.md. A single-file Emacs package is easy to read end to end, which was part of the appeal and also part of why the extension ecosystem around it needed a successor.

## Sorting, filtering, and the two packages that made it clever

The default behaviour is deliberately plain, and that is the baseline the extensions build on.

The default sorting method of Selectrum is simple and predictable. The candidates are first sorted by their history position, then by length and then alphabetically. The default filtering uses the Emacs completion-styles variable, and the readme is candid that the default setting of that variable is rather basic and that you may want to adjust it, pointing at the built-in substring and flex styles.

Instead of using the built-in completion styles the authors recommend two additional packages for more advanced filtering and sorting: Prescient and Orderless.

Prescient comes from MELPA and is enabled with:

```elisp
;; to make sorting and filtering more intelligent
(selectrum-prescient-mode +1)

;; to save your command history on disk, so the sorting gets more
;; intelligent over time
(prescient-persist-mode +1)
```

The behaviour it adds is specific. Candidates are sorted by frecency, a combination of frequency and recency, so recently used candidates come first, then frequently used ones, and the rest by length. The readme's assessment is that this algorithm turns out to do very well in practice while being fast and not very magical.

For filtering, the input is split on spaces into subqueries, each of which must by default match as either a substring, a regexp or an initialism, with the example given being that ffap matches find-file-at-point. The subqueries can match a candidate in any order, but a candidate must match all subqueries to remain in the list. Other matching styles are available in addition to the default three, custom styles can be added by users, and filtering features can be toggled on the fly, such as whether to use character and case folding.

## The Makefile shows how a single-file Emacs package stays honest

The build tooling is small but it is worth looking at, because it explains the shape of the repository and the quality bar the project held itself to.

The Makefile has a lint target that depends on compile, checkdoc, longlines, checkindent and toc, so a single make lint runs the whole set. The compile target byte-compiles the sources with emacs -Q --batch and fails the build on any warning other than the Wrote lines, so a byte-compile warning is a build failure rather than noise. The checkdoc target runs checkdoc-file to check docstring style, and the longlines target calls scripts/check-line-length.bash, which is why the readme has longlines-start and longlines-stop comment markers around the sections that are allowed to exceed the limit, such as the table of contents.

The checkindent target is the most interesting one. It loads the package in a batch Emacs, reindents the region of each file, writes the result to a temporary directory, and diffs it against the original, so an indentation change is a failing check rather than something a contributor has to notice.

The Dockerfile is a container for a reproducible development environment rather than a deployment artefact. It takes a silex/emacs image tagged by a VERSION build argument, copies in scripts/docker-install.bash, switches to a non-root USER and sets the working directory to /home/docker/src, with the default command being bash.

So a project whose entire code is one file still had a byte-compile gate, a docstring gate, a line length gate, an indentation gate and a container for its checks. That discipline is part of why the maintainers could hand the project over with confidence rather than abandoning it.

## The comparison table is a list of other people's packages

The readme carries a comparison section that reads more like a list of alternatives than a comparison: Selectrum in comparison to other completion-systems, with entries for Ido, Helm, Ivy, Icomplete, Vertico, Icicles, Snails, Sallet, Raven and Swiper.

That table is the most useful single artefact in the repository for a new user, and it also explains why the handover was not controversial. Selectrum positioned itself against Helm, Ivy and Ido as a better solution for incremental narrowing, and the table is a candid accounting of the whole neighbourhood of Emacs completion packages.

What the table cannot tell you from this excerpt is the detail of each comparison. The section is present in the readme, but the excerpt available here stops before the entries, so the specific arguments made about Ido's ordering, Helm's breadth, Ivy's integration and Swiper's model are not something you can read in this copy. The same applies to the Caveats section, which the table of contents lists but the excerpt truncates, and to the second filtering alternative, Orderless, whose section header is present but whose body is cut off.

That is the honest limitation of judging this project from its readme as published here. The two sections you would most want before choosing between Selectrum and Vertico, the caveats and the Orderless details, are the two that are not visible.

What is visible is the shape of the argument. Selectrum was one of several attempts to give Emacs a good completion interface, it chose the standard API path, it added two optional extensions for smarter ranking, and its maintainer decided the ecosystem needed one well maintained implementation rather than several, and named which one.

## Where Selectrum is the wrong choice today

There is a short list of cases where picking Selectrum is a mistake, and the list is short because the project itself says so.

The first and largest is a new configuration. If you are setting up Emacs today, there is no reason to start with a package whose documentation tells you it has been replaced. The migration guide exists, but starting at the destination is less work than starting at the origin and moving.

The second is a configuration that depends on the extensions rather than the core. If your setup leans on the Prescient style with frecency ranking, or on the Orderless behaviour, then the question is not Selectrum against Vertico but which of those extension behaviours you want, and whether Vertico's ecosystem already covers it. The readme says feature parity for existing Selectrum configurations is being worked toward in the Vertico ecosystem, possibly using one or more Vertico extension packages of which there are many already. That is a statement of intent rather than a guarantee of equivalence today, so anyone with a heavily customised setup should read the caveats and the parity work before assuming a clean port.

The third is a package that no longer receives features. The release history shows v3.0 on 2020-07-18, v3.1 on 2021-02-21, and nothing since. The repository is not archived and the last push was on 2026-04-20, so there is still activity, but it is activity on a project whose development has formally moved elsewhere. New features will not land here.

The fourth is a team with several configurations. If a group shares an Emacs setup, having one package that is a documented dead end is a tax on everyone, and the fix is the migration rather than the exception.

## Conclusion

Adopt Vertico instead of Selectrum if you are starting fresh, because the Selectrum readme itself names Vertico as the replacement and the author's own configuration uses it. Only carry Selectrum forward if you already depend on it and cannot migrate yet, in which case the migration guide in the Vertico wiki is the concrete next step. Verify first which of the two filtering extensions, Prescient or Orderless, matches the completion behaviour you rely on, and check the caveat list in the Selectrum readme before assuming a configuration will port across unchanged.

## FAQ

### Is Selectrum still maintained?

Its readme states that Selectrum has been replaced by Vertico, and the original author now uses Vertico in the Radian configuration. The repository is not archived and the last push was on 2026-04-20, but the last tagged release was v3.1 in 2021 and development has moved to the replacement.

### How do I install and enable Selectrum in Emacs?

It is available as a package on MELPA, and the easiest way to install it is with straight.el using (straight-use-package 'selectrum). You then add (selectrum-mode +1) to your init-file, and all completion commands will automatically use Selectrum.

### What does Selectrum use for filtering and sorting by default?

By default candidates are sorted by history position, then by length, then alphabetically, and filtering uses the Emacs completion-styles variable. The readme notes the default completion-styles setting is rather basic and points at the built-in substring and flex styles, and recommends the Prescient and Orderless packages for more advanced behaviour.

### How do I migrate from Selectrum to Vertico?

There is a guide to migrate from Selectrum to Vertico in the Vertico wiki. The Selectrum team says it will improve the guide over time to achieve feature parity for existing Selectrum configurations in the Vertico ecosystem, possibly using one or more Vertico extension packages.

### What are the extra packages that make Selectrum's filtering smarter?

Two. Prescient, installed from MELPA and enabled with (selectrum-prescient-mode +1), sorts by frecency and splits input into space separated subqueries that must each match as a substring, a regexp or an initialism. The second is Orderless, described in the readme as the other recommended approach.

### What licence is Selectrum released under?

MIT, with the licence text in LICENSE.md at the root of the repository. The package is also listed on MELPA and on MELPA Stable, so it remains installable despite the handover.

## Sources

- [Issues](https://github.com/radian-software/selectrum/issues)
- [License: MIT](https://github.com/radian-software/selectrum/blob/master/LICENSE)
- [radian-software/selectrum on GitHub](https://github.com/radian-software/selectrum)
- [README](https://github.com/radian-software/selectrum/blob/master/README.md)
- [Releases](https://github.com/radian-software/selectrum/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/radian-software-selectrum