Deprecated

• The selectrum-read API has been deprecated and made private. The intention of this change is to encourage users instead to rely on the plain completing-read function, which is completion system agnostic ([#446]).
• The user option selectrum-fix-minibuffer-height has been deprecated. The new variable selectrum-fix-vertical-window-height takes its place ([#305]).
• The special text property selectrum-candidate-full to change the canonical representation of a candidate has been deprecated ([#403]).
• The hooks selectrum-candidate-inserted-hook and selectrum-candidate-selected-hook originally also received the arguments passed to selectrum-read which has been deprecated. These hooks are expected to be updated to only receive a single argument now, the inserted/selected candidate ([#446]).
• selectrum-default-candidate-refine-function and selectrum-default-candidate-highlight-function have been deprecated, see the new default values for selectrum-refine-candidates-function and selectrum-highlight-candidates-function which should be used instead ([#330]).

Changed defaults

• The default value of selectrum-num-candidates-displayed has changed to auto. If you have customized selectrum-num-candidates-displayed you should remove that from your configuration or also adjust it to auto. For configuring the window height you should use the new selectrum-max-window-height option now ([#305]).
• The new default functions used for selectrum-refine-candidates-function and selectrum-highlight-candidates-function have been updated to filter and highlight candidates according to completion-styles now ([#330]).

Features

• Line spacing is taken into account when using a fixed window height ([#424], [#432]).
• The new option selectrum-max-window-height can now be used to configure the maximal display window height analogue to the built-in max-mini-window-height. The new option replaces the usage of the formerly used selectrum-num-candidates-displayed setting which is now set to auto by default. By using auto the number of candidates is automatically determined using the available space and current display settings. When setting the value to a number this will determine the actual amount of displayed candidates without having an effect on the window height ([#305]).
• The option selectrum-display-style can be used to configure the display style for candidates. Vertical and horizontal display styles are included and you can cycle through styles using the new selectrum-cycle-display-style command which uses the selectrum-display-style-cycle-list option for cycling ([#305]).
• selectrum-exhibit got an optional argument which allows to keep the current candidate selected after the update which is helpful for async completions ([#306], [#307], [#349]).
• The user option selectrum-display-action can be used to show candidates in another window or frame ([#230], [#309]).
• The user option selectrum-show-indices can now be a function that can be used to control the display of the a candidate's index ([#200]).
• The user option selectrum-extend-current-candidate-highlight determines whether to extend the highlighting of the current candidate until the margin (the default is nil). See [#208].
• The user option selectrum-complete-in-buffer can be used to control whether Selectrum should handle in buffer completion (the default is t) ([#261]).
• The user option selectrum-default-value-format can be used to specify the formatting of the default value indicator ([#445]).

Enhancements

• When hovering over candidates with the mouse there are no messages shown anymore which avoids interference with candidates display ([#452]).
• The variable selectrum-should-sort-p and selectrum-active-p have been marked deprecated. You should use the new selectrum-should-sort and selectrum-is-active. selectrum-should-sort is also exposed as a user option now ([#441]).
• The variable selectrum-move-default-candidate can be used to configure how the UI handles the default value ([#441]).
• The command selectrum-repeat can also repeat the last recursive session now ([#322], [#440]).
• The default value of selectrum-extend-current-candidate-highlight has been changed to auto which will automatically extend the highlighting if the session uses annotations ([#427], [#430]).
• The accessibility of the default value in file completions has been improved. When the default exists in the prompting directory it gets sorted first otherwise the default is included as a virtual candidate ([#400], [#420], [#421]).
• Depending on the used font and display settings like line-spacing the minibuffer height could be slightly off so that the displayed candidates wouldn't be completely visible, which has been fixed ([#303], [#414]).
• The sorting of passed defaults for file completions has been improved such that paths like "/home/user/default", "~/default" or a relative passed default get sorted first when they exist within the prompting directory ([#402], [#404]).
• Tramp completions have been improved. You now get completion for tramp methods and hosts. If a connection hasn't been established yet and you are manually typing the path, a message is shown that you can refresh using selectrum-insert-current-candidate which helps correcting typos before trying to establish a new connection. Lastly if tramp would error or you would quit from a password prompt Selectrum stopped working until you restarted the session, which has been fixed ([#392], [#394], [#405], [#408]).
• Selectrum will allow recursive sessions for selectrum-completion-in-region and selectrum-select-from-history so these commands work even if enable-recursive-minibuffers is not set by the user ([#100], [#397]).
• In file completions where the directory path of the input does not exist, the candidates are automatically gathered by interpreting the input as an partial-completion style input pattern (see completion-styles-alist). For example the input "/us/l/bi/" would give results for "/usr/local/bin/". With tramp paths this has to be triggered manually using selectrum-insert-current-candidate to avoid possible speed problems ([#390], [#393]).
• You can now complete environment variables in file completions by typing a "$" after a "/" ([#386], [#389]).
• The selectrum-select-from-history command has been improved. You can now insert a history item into the previous session using your default binding for selectrum-insert-current-candidate. To submit the history item and exit use selectrum-select-current-candidate ([#362]).
• When using commands where the prompt would exceed the window width the horizontal scroll wouldn't reset afterwards when a smaller element was pulled into the prompt under certain conditions (for example when using history commands), which has been fixed ([#360]).
• When the prompt is empty and the default value is shown you can now insert it using selectrum-insert-current-candidate. Also selectrum-insert-current-candidate now moves point to end of the prompt even when there were no candidate insertion to have consistent UI behaviour ([#359], [#369]).
• selectrum-insert-current-candidate will reset minibuffer-history-position, so that after "choosing" an item and using other history commands in succession the history will start from the beginning ([#361], [#368]).
• History commands don't automatically trigger a refresh for tramp paths. This is useful to prevent unintended opening of tramp connections. To trigger a refresh for the selected tramp path you can use selectrum-insert-current-candidate ([#358], [#361], [#365], [#367], [#368], [#372]).
• In file completions the prompt will also be selected when a match is required and the path exists ([#357]).
• Improved selection behaviour for history commands. When using next-history-element, previous-history-element or isearch for history browsing the inserted history element will get selected when a match isn't required ([#323], [#324], [#341], [#346], [#380]).
• Improved exit behaviour of selectrum-select-current-candidate. The commands gives feedback now when match is required and submission not possible. Also it allows submission of the prompt when a match is required and the prompt is a member of candidates ([#338]).
• You can now configure the initial filtering for candidates in selectrum-completion-in-region using selectrum-completion-in-region-styles ([#331], [#356]).
• Computation of candidates is faster for describe-variable ([#312], [#316], [#320], [#321], [#343]).
• Candidates of completing-read-multiple which are submitted by selectrum-select-current-candidate are now passed to selectrum-candidate-selected-hook one by one in the order they were added. Before the hook would not run for the multi candidates case ([#296]).
• File completions are faster because the internal handling was updated ([#334], [#335], [#339]). Most notably recomputation only happens on directory change now. Before, the candidates where recomputed on each input change which could slow down file completions significantly for cases where read-file-name-internal would be slow already ([#210], [#276], [#277]).
• You can now give a prefix argument to selection moving commands ([#275]).
• If completion table metadata or completion-extra-properties define an affixation-function (introduced in Emacs 28) Selectrum will use this information to annotate the candidates accordingly ([#240], [#271], [#286], [#288], [#289]).
• The argument passed to selectrum-select-current-candidate and selectrum-insert-current-candidate is now used to choose the nth displayed candidate instead of calculating an index based on the currently selected candidate ([#194], [#215]).
• selectrum-insert-current-candidate no longer adds inserted candidates to the history ([#212], [#213]).
  ...

Breaking changes

• The function selectrum-read-directory-name is no longer available.
• When reading directories and the default is already in the prompt, it gets selected so you can immediately submit it (#126, #127). In correspondence with this change, the initial working directory for read-directory-name is now unchanged from the Emacs default, rather than being the parent directory.
• Selectrum now uses a keymap (selectrum-minibuffer-map) instead of an alist (selectrum-minibuffer-bindings, now removed) for configuring bindings (#186). This better meets users' expectations, and allows other packages (e.g., General) to better work with Selectrum's keybindings (#71).

Features

• The user option selectrum-completing-read-multiple-show-help can be used to control display of additional usage information in the prompt in a completing-read-multiple session (#130, #132).
• selectrum-read accepts two additional keyword arguments minibuffer-completion-table and minibuffer-completion-predicate. These can be used to pass the completing-read collection and predicate so they are available for internal handling of completion API features and for other external commands or packages which make use of them (#94, #95).
• If the completion table passed to completing-read provides annotation-function or display-sort-function in its metadata, Selectrum will use this information to annotate or sort the candidates accordingly. Annotations defined by completion-extra-properties are handled, too (#82, #95).
• One can trigger an update of Selectrum's completions UI manually by calling selectrum-exhibit (#95).
• You can now interact with candidates via the mouse. Left click (mouse-1) selects the candidate, and right click (mouse-3) inserts the candidate, just like RET and TAB, respectively. See #113 and #118.

Enhancements

• If selectrum-candidate-display-right-margin is used the margin is included in the highlighting of the selected candidate so it's easier to see to which candidate the margin belongs to (#166).
• If the default-filename passed to selectrum-read-file-name is an absolute path it will still be sorted to the top when it is contained in the prompting directory (#160).
• icomplete-mode is now automatically disabled when entering Selectrum, to avoid conflicts (#99).
• Working with the default candidate has been improved in cases where it is not in the candidate list. Such candidates are currently shown in the prompt message. For example, the command lgrep might suggest searching through files matching *.el instead of just a specific file. See #120, #122.
  • While there is no user input, the default candidate remains visible in the prompt message. Previously, it would be hidden when the prompt line was not selected. Unchanged is the behavior is to hide the default candidate when text is typed, so that it is only visible when it can be submitted (similar to the effect of minibuffer-electric-default-mode).
  • The default candidate shown in the prompt message is now displayed with the face selectrum-current-candidate when it is selected.
  • Now that Selectrum always shows the default candidate when it can be submitted, it now attempts to remove the default candidate from prompt messages that already contain it. This decreases redundancy.
• When there is no default value the prompt shows [default-value : ""] to indicate that you would submit the empty string. Previously it showed [default-value: none] (#133).
• When reading file names spaces are now considered symbol constituents which means you can use s-expression commands to navigate and edit the input more efficently. A binding for backward-kill-sexp was added to go up a directory with C-M-DEL (#138).
• Compliance to default minibuffer API has been further improved by using an overlay for candidates display. Previously code which assumed that the minibuffer only contains user input would be likely to fail (#124). This also means inside the minibuffer minibuffer-contents now returns only the current input as expected (#116, #133).
• Multiline candidates are now merged into a single truncated line so there is no gradual scrolling effect anymore when going through the candidate list. The first matched line is shown in front of the merged lines (#133). This formatting is customizable via selectrum-multiline-display-settings (#147).
• selectrum-insert-current-candidate now automatically inserts the separator for common values of crm-separator when using completing-read-multiple (#197).

Bugs fixed

• The minibuffer height is now determined by the actual height of displayed candidates. Previously the height could be off for candidates containing unicode characters or other means which changed the display height such as line-spacing (#146, #151, #154).
• When passing a named function or compiled lambda as CANDIDATES argument to selectrum-read an error would be thrown, which has been fixed (#163).
• When selecting file name prompts and submitting them the result will be the selected prompt. Previously it could be the default file name passed to selectrum-read-file-name which is the behavior of default completion where there is no concept of an active selection (#157, #160).
• When there are no candidates and a match isn't required the prompt will now be shown as selected to indicate one can submit the input (#160).
• If the MUSTMATCH argument to read-directory-name was non-nil the selection of the prompt wasn't visible which has been fixed (#157, #160).
• If a predicate was passed to read-buffer an error would be thrown which has been fixed (#159, #161).
• Dynamic collection functions can now reuse their returned candidates. Previously Selectrum could modify them even when the :may-modify-candidates argument wasn't passed to selectrum-read.
• Incremental history search via isearch wasn't working which has been fixed (#124, #133).
• Empty string completion candidates are now ignored like in the default completion UI (#101).
• Text properties are now stripped for standard completion functions (#107, #108).
• You can now select and submit empty input and for file prompts existing paths when require-match is non-nil (#67, #125).
• The default candidate is now first selected, even when it is not in the candidate list, conforming with expectations. Previously, the first candidate in the list was selected instead. See #120.
• selectrum-insert-current-candidate now works correctly for completing-read-multiple when crm-separator has a non default value. Previously it would replace the separator with commas when adding new candidates (#140).
• selectrum-insert-current-candidate now works from selectrum-select-from-history and other commands which ignore history by setting minibuffer-history-variable to t. Previously an error would be thrown (#152).
• When completing filenames and a match is required, non-normalized paths (e.g., ~/Documents//etc/hosts) are accepted (#190).
• Pressing TAB when nothing matches shows a “No match” message in the minibuffer instead of signaling an error and erasing the minibuffer contents (#193). If completion-fail-discreetly is non-nil, nothing is done.
• Fix type mismatch when configuring selectrum-count-style in customizations.
• Submitting the default value with the empty prompt does no longer strip the text properties of the default candidate (#180, #198).

Breaking changes

• The way to dynamically generate the candidate list has changed.

  Instead of rebinding selectrum-preprocess-candidates-function and selectrum-refine-candidates-function, you simply pass a function as the COLLECTION argument to selectrum-read. This function takes one argument, the current user input, and returns the list of candidates as strings. Alternatively, it can return an alist whose candidates key is the candidate list and whose input key is a transformed user input to use for highlighting.

  As part of this change, selectrum-refine-candidates-function no longer can return an alist; that functionality should instead be moved to the CANDIDATES function. (This feature was never properly supported in the first place if you tried to use it in a way that can't be done equivalently in the CANDIDATES function.)

  See #27.

Features

• You can now give a prefix argument to selectrum-insert-current-candidate to insert the candidate at a given index directly (#96).
• Candidates inserted by selectrum-insert-current-candidate are now added to history (#54).
• You can resume the last completion session using the selectrum-repeat command. (Note that you must bind this command to a key sequence in order to use it.) This command implements similar functionality to ivy-resume. See #39.
• Experimental support for using Selectrum as a backend for Helm commands. Use it by enabling selectrum-helm-mode from the selectrum-helm library. See #18.
• You can now give a prefix argument to selectrum-select-current-candidate to select the candidate at a given index directly. New user option selectrum-show-indices to display these indices for your convenience. This feature implements similar functionality to ivy-avy. See #16.
• Recursive minibuffers are now supported.
• In the standard completing-read interface, you can use previous-matching-history-element to retrieve history elements. The binding now works properly in Selectrum too, except that you can use Selectrum to select a history element. See #49, #77. If you prefer to use the original interface you can use selectrum-previous-history-element which is just not bound by default #57.
• You can now cause the minibuffer to always have the same height, even if there are fewer candidates, by enabling selectrum-fix-minibuffer-height (#35).
• Multiple candidate selection is now supported, and we provide a selectrum-completing-read-multiple function which is installed automatically by selectrum-mode. This means that commands like describe-face (which delegate to completing-read-multiple internally) now use Selectrum by default. To select additional candidates within a supported command, use TAB and input crm-separator (, by default). See #53, #80, #74.
• We provide a selectrum-completion-in-region function now and install it on completion-in-region-function in selectrum-mode, so completion-at-point will use Selectrum when there is more than one completion (#42). This function can display annotation informations if the completion-at-point-function backend offers them (#62), and will respect completion boundaries (#89). Appearance can be configured using the faces selectrum-completion-annotation, selectrum-completion-docsig, and completions-common-part (#86).

Enhancements

• selectrum-read-file-name which is used as read-file-name-function now uses read-file-name-default internally. This means all default features of file completion should be available now. Most notably you can now use M-n to insert file names into the minibuffer (using file-name-at-point-functions) and you are able to use shortcuts like // or ~/ (#50, #52).
• In read-file-name, when a default is provided (for example in the dired-do-rename command), we actually use it as the initial contents of the minibuffer, which allows you to have convenient access to the default filename when that default file does not exist (#25).
• We now bind minibuffer-completing-file-name during read-file-name, in conformance with the standard Emacs interface (#30).
• A new text property selectrum-candidate-display-right-margin is added, to display a string at the right margin after a candidate (#44).
• You can now access standard minibuffer history using M-p and M-n (#4, #38).
• Previously, setting resize-mini-windows to nil would cause Selectrum to be unable to display any candidates. This has been fixed by having Selectrum bind the variable to grow-only when entering the minibuffer (#35).
• Previously, a large value of selectrum-num-candidates-displayed would produce a confusing result because max-mini-window-height imposed a lower limit on the height of the minibuffer. Now that variable is bound automatically by Selectrum based on the value of selectrum-num-candidates-displayed (#22).
• Multiline candidates are now displayed properly and do not mess up scrolling in the candidate list (#12).
• When you select the user input area and it doesn't have anything typed, we now show an overlay indicating that you are in this state, so it is less confusing. The overlay shows what default value will be submitted if you press return. See #55.
• Switching buffers is now less confusing, because we don't modify the order of the buffer list at all. Previously the default buffer to switch to was moved to the top of the list. Now we leave it where it is, and just select it initially. selectrum-read grows a new argument :no-move-default-candidate to support this improvement.
• Previously, selectrum-read sometimes modified the list of candidates it was given. This has been fixed, and there is a new keyword argument :may-modify-candidates to re-enable the old behavior for cases where it is safe and the performance gains are useful. See #74.

Bugs fixed

• You can now use the undo system in the minibuffer. Previously, trying to do so would break Selectrum (#31).
• Passing a list of symbols to selectrum-completing-read works now.
• Previously, selectrum-read-buffer ignored its PREDICATE argument. This has now been fixed (#32, #33).
• Previously, selectrum-read would return nil when selectrum-submit-exact-input was used on an empty input and no :default-candidate was provided. Now the empty string is returned, in accordance with the completing-read API (#34).
• The keymap used in the minibuffer now inherits from minibuffer-local-map, so standard minibuffer bindings should still work (raxod502/ctrlf#41).
• The application of face selectrum-current-candidate does not trample on the results of selectrum-highlight-candidates-function. In other words, the matched part of the current candidate is now highlighted just like the matched part of the other candidates. See (#21, #76).
• Previously, an error was thrown if you used certain non-Selectrum minibuffer commands before loading Selectrum. This has been fixed (#28).
• If selectrum-num-candidates-displayed is set to one, the highlighting now works correctly. Before, the prompt would get highlighted instead of the current candidate. See #85.
• selectrum-read-library-name previously, in certain versions of Emacs, showed some entries with .el appended. This has now been fixed. Also, TAB now inserts the current candidate and not the whole path to the library, so that the result can be submitted directly (#73).

Added

• Package selectrum
• Minor mode selectrum-mode
• Faces:
  • selectrum-current-candidate
  • selectrum-primary-highlight
  • selectrum-secondary-highlight
• Interface user options:
  • selectrum-num-candidates-displayed
  • selectrum-minibuffer-bindings
  • selectrum-count-style
• Commands bound in minibuffer:
  • selectrum-previous-candidate
  • selectrum-next-candidate
  • selectrum-previous-page
  • selectrum-next-page
  • selectrum-goto-beginning
  • selectrum-goto-end
  • selectrum-kill-ring-save
  • selectrum-select-current-candidate
  • selectrum-submit-exact-input
  • selectrum-insert-current-candidate
• Entry points:
  • selectrum-read
  • selectrum-completing-read
  • selectrum-read-buffer
  • selectrum-read-file-name
  • selectrum-read-directory-name
  • selectrum-read-library-name
• Hooks:
  • selectrum-candidate-selected-hook
  • selectrum-candidate-inserted-hook
• API user options, variables, and functions:
  • selectrum-refine-candidates-function
  • selectrum-default-candidate-refine-function
  • selectrum-preprocess-candidates-function
  • selectrum-default-candidate-preprocess-function
  • selectrum-highlight-candidates-function
  • selectrum-default-candidate-highlight-function
  • selectrum-should-sort-p