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 his Emacs configuration, Radian.

There is a guide to migrate from Selectrum to Vertico.

Over time, we 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).

It's always annoying to change from one thing to another, but we (the Selectrum development team) think 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.

Documentation

News feed

Selectrum is a better solution for incremental narrowing in Emacs, replacing Helm, Ivy, and Ido.

<!-- longlines-start --> <!-- toc -->

• What is it?
• Installation
• Usage
  • Alternative 1: Prescient
  • Alternative 2: Orderless
• User guide
  • Keybindings
  • Sorting and filtering
  • Additional features
  • Customization
  • Complementary extensions
  • But what is it doing to my Emacs??
  • News
• Developer guide
  • Usage of Selectrum
  • Sorting, filtering, and highlighting
  • Text properties
  • Hooks
  • Variables
• Contributor guide
• Caveats
• Selectrum in comparison to other completion-systems
  • Ido
  • Helm
  • Ivy
  • Icomplete
  • Vertico
  • Icicles
  • Snails
  • Sallet
  • Raven
  • Swiper

<!-- tocstop --> <!-- longlines-stop -->

What is it?

Selectrum aims to provide a better completion UI using standard Emacs APIs. In essence it is an interface for selecting items from a list.

You can use it to run a command with M-x:

<p align="center"> <img src="images/commands.png" alt="Picking from a list of commands" height="200"/> </p>

You can use it to open a file with C-x C-f (find-file):

<p align="center"> <img src="images/files.png" alt="Navigating the filesystem" height="200"/> </p>

Even TRAMP works great out of the box:

<p align="center"> <img src="images/tramp.png" alt="Using sudo via TRAMP" height="200"/> </p>

You can switch buffers:

<p align="center"> <img src="images/buffers.png" alt="Switching to another buffer" height="200"/> </p>

And every other command in Emacs is automatically enhanced, without the need for any configuration:

<p align="center"> <img src="images/libraries.png" alt="Finding libraries, with load-path shadows" height="200"/> </p>

Installation

Selectrum is available as a package on MELPA. The easiest way to install this package is using straight.el:

(straight-use-package 'selectrum)

However, you may install using any other package manager if you prefer.

Usage

To enable Selectrum, simply add to your init-file:

(selectrum-mode +1)

Now all completion commands will automatically use Selectrum.

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. Many tips and setup help for integration with other packages can be found in our wiki.

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 of Selectrum uses the Emacs completion-styles. The default setting of the completion-styles variable is rather "basic" and you may want to adjust this variable for more advanced filtering. See for example the built-in substring and flex styles. Instead of using the built-in completion styles we recommended to use additional packages. Here we highlight two possible approaches for more advanced filtering and sorting: 1. Prescient and 2. Orderless.

Alternative 1: Prescient

Filtering and sorting can both be improved by installing the selectrum-prescient package from MELPA and adding the following to your init-file.

;; 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)

• Your candidates are sorted by frecency (a combination of frequency and recency). Recently used candidates are sorted first, then frequently used candidates. The remaining candidates are sorted by length. This algorithm turns out to do very well in practice while being fast and not very magical.
• Your input is split on spaces into subqueries, each of which must (by default) match as either a substring, a regexp, or an initialism (e.g. 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 of filtered candidates.
  • Other matching styles are available in addition to the default three, and custom styles can be added by users.
  • Filtering features can be toggled on the fly, such as whether to use character/case folding or which matching styles are active.
  • Optionally, fully matched candidates can be listed before partially matched candidates while keeping the frecency-based sorting.
• The parts of each candidate that matched your input are highlighted, with important sections within each part (such as the initials of an initialism) highlighted in a second color.

Alternative 2: Orderless

Another popular choice for filtering is to use the flexible orderless completion style.

(setq completion-styles '(orderless))

;; Persist history over Emacs restarts
(savehist-mode)

;; Optional performance optimization
;; by highlighting only the visible candidates.
(setq orderless-skip-highlighting (lambda () selectrum-is-active))
(setq selectrum-highlight-candidates-function #'orderless-highlight-matches)

The candidates are sorted using the default sorting method of Selectrum (by recency). The history is persisted using the Emacs built-in savehist-mode. Afterwards the candidates are filtered and highlighted using the completion-styles, in this case orderless.

In some cases you may want to consider to use Prescient on top of Orderless. Prescient can be used to provide frecency-based sorting (a combination of frequency and recency) and history persistence by adding the following.

(setq selectrum-prescient-enable-filtering nil)
(selectrum-prescient-mode +1)
(prescient-persist-mode +1)

User guide

The design philosophy of Selectrum is to be as simple as possible, because selecting an item from a list really doesn't have to be that complicated, and you don't have time to learn all the hottest tricks and keybindings for this. What this means is that Selectrum always prioritizes consistency, simplicity, and understandability over making optimal choices for workflow streamlining. The idea is that when things go wrong, you'll find it easy to understand what happened and how to fix it.

Keybindings

• To navigate to a candidate: use the standard motion commands (<up>, <down>, C-v, M-v, M-<, M->). If you prefer, you can use C-p and C-n instead of the arrow keys.
• To navigate to a group of candidates: use M-{ (remapped from backward-paragraph) and M-} (remapped from forward-paragraph) to move to the previous and next group, respectively. You can also use C-M-p and C-M-n.
• To accept the currently selected candidate: type RET/C-m. (With a prefix argument, accept instead the candidate at that point in the list, counting from one. See selectrum-show-indices. The value zero means to accept exactly what you've typed, as in the next bullet point.) You can also click the left mouse button on a candidate to choose it or use M-m to select one using selectrum-quick-keys.
• To submit what you've typed, even if it's not a candidate: you can use <up> or C-p to select the user input just like a regular candidate, and type RET as usual. (Alternatively, you can type