To install this package, run in Emacs:
M-x package-install RET orderless RET
This package provides an
orderless completion style that divides the
pattern into space-separated components, and matches candidates that
match all of the components in any order. Each component can match in
any one of several ways: literally, as a regexp, as an initialism, in
the flex style, or as multiple word prefixes. By default, regexp and
literal matches are enabled.
A completion style is a back-end for completion and is used from a front-end that provides a completion UI. Any completion style can be used with the default Emacs completion UI (sometimes called minibuffer tab completion), with the built-in Icomplete package (which is similar to the more well-known Ido Mode), or with some third party minibuffer completion frameworks such as Vertico, Selectrum (in its default configuration), or icomplete-vertical (note there is also a built-in package named icomplete-vertical in the unreleased version 28 of Emacs, which will eventually make the third party icomplete-vertical obsolete —orderless works equally well with both icomplete-vertical packages).
All the completion UIs just mentioned are for minibuffer completion,
used when Emacs commands prompt the user in the minibuffer for some
input, but there is also completion at point in normal buffers,
typically used for identifiers in programming languages. Completion
styles can also be used for that purpose by completion at point UIs
such as Corfu, Company or the function
To use a completion style with any of the above mentioned completion
UIs simply add it as an entry in the variables
completion-category-overrides (see their documentation). You may also
want to modify the
completion-category-defaults variable, which serves
as a default value for
completion-category-overrides: if you want to
orderless exclusively, set both variables to
With a bit of effort, it might still be possible to use
other completion UIs, even if those UIs don't support the standard
Emacs completion styles. Currently there is support for Ivy (see
below). Also, while Company does support completion styles directly,
SPC takes you out of completion, so comfortably using
orderless with it takes a bit of configuration (see below).
If you use MELPA, the easiest way to install
orderless is via
package-install. If you use both MELPA and
use-package, you can use:
(use-package orderless :ensure t :custom (completion-styles '(orderless)))
orderless.el somewhere on your
load-path, and use
the following configuration:
(require 'orderless) (setq completion-styles '(orderless))
Bug reports are highly welcome and appreciated!
Each component of a pattern can match in any of several matching styles. A matching style is simply a function from strings to strings that maps a component to a regexp to match against, so it is easy to define new matching styles. The predefined ones are:
the component is treated as a regexp that must match somewhere in the candidate.
If the component is not a valid regexp, it is ignored.
the component is treated as a literal string that must occur in the candidate.
This is just
the component is a treated as a literal string that must not occur in the candidate.
Note that nothing is highlighted for this matching style. You
probably don't want to use this style directly in
orderless-matching-styles but with a style dispatcher instead. There
is an example in the section on style dispatchers.
the component is split at word endings and each piece must match at a word boundary in the candidate, occurring in that order.
This is similar to the built-in
each character of the component should appear as the beginning of a word in the candidate, in order.
the characters of the component should appear in that order in the candidate, but not necessarily consecutively.
orderless-matching-styles can be set to a list of the
desired matching styles to use. By default it enables the literal and
For more fine-grained control on which matching styles to use for
each component of the input string, you can customize the variable
Style dispatchers are functions which take a component, its index in the list of components (starting from 0), and the total number of components, and are used to determine the matching styles used for that specific component, overriding the default matching styles.
A style dispatcher can either decline to handle the input string or
component, or it can return which matching styles to use. It can
also, if desired, additionally return a new string to use in place of
the given one. Consult the documentation of
As an example, say you wanted the following setup:
~should match (the characters other than the final
~) in the flex style, and
!should indicate the rest of the component is a literal string not contained in the candidate.
You can achieve this with the following configuration:
(defun flex-if-twiddle (pattern _index _total) (when (string-suffix-p "~" pattern) `(orderless-flex . ,(substring pattern 0 -1)))) (defun first-initialism (pattern index _total) (if (= index 0) 'orderless-initialism)) (defun without-if-bang (pattern _index _total) (cond ((equal "!" pattern) '(orderless-literal . "")) ((string-prefix-p "!" pattern) `(orderless-without-literal . ,(substring pattern 1))))) (setq orderless-matching-styles '(orderless-regexp) orderless-style-dispatchers '(first-initialism flex-if-twiddle without-if-bang))
The pattern components are space-separated by default: this is
controlled by the variable
orderless-component-separator, which should
be set either to a regexp that matches the desired component
separator, or to a function that takes a string and returns the list
of components. The default value is a regexp matches a non-empty
sequence of spaces. It may be useful to add hyphens or slashes (or
both), to match symbols or file paths, respectively.
Even if you want to split on spaces you might want to be able to
escape those spaces or to enclose space in double quotes (as in shell
argument parsing). For backslash-escaped spaces set
orderless-component-separator to the function
orderless-escapable-split-on-space; for shell-like double-quotable
space, set it to the standard Emacs function
If you are implementing a command for which you know you want a
different separator for the components, bind
orderless-component-separator in a
Orderless allows the definition of custom completion styles using the
orderless-define-completion-style macro. Any Orderless configuration
variable can be adjusted locally for the new style, e.g.,
By default Orderless only enables the regexp and literal matching
styles. In the following example an
orderless+initialism style is
defined, which additionally enables initialism matching. This completion
style can then used when matching candidates of the symbol or command
(orderless-define-completion-style orderless+initialism (orderless-matching-styles '(orderless-initialism orderless-literal orderless-regexp))) (setq completion-category-overrides '((command (styles orderless+initialism)) (symbol (styles orderless+initialism)) (variable (styles orderless+initialism))))
Note that in order for the
orderless+initialism style to kick-in with
the above configuration, you'd need to use commands whose metadata
indicates that the completion candidates are commands or symbols. In
execute-extended-command has metadata indicating you are
selecting a command, but earlier versions of Emacs lack this metadata.
marginalia-mode from the Marginalia package provides this
metadata automatically for many built-in commands and is recommended
if you use the above example configuration, or other similarly
fine-grained control of completion styles according to completion
The portions of a candidate matching each component get highlighted in
one of four faces,
? is a number from 0
to 3. If the pattern has more than four components, the faces get
completion-category-overrides for some
particular category) has more than one entry, remember than Emacs
tries each completion style in turn and uses the first one returning
matches. You will only see these particular faces when the
completion is the one that ends up being used, of course.
The default mechanism for turning an input string into a list of regexps to
match against, configured using
orderless-matching-styles, is probably
flexible enough for the vast majority of users. The patterns are compiled by the
orderless-pattern-compiler. Under special circumstances it may be useful to
implement a custom pattern compiler by advising the
You might want to change the separator or the matching style
configuration on the fly while matching. There many possible user
interfaces for this: you could toggle between two chosen
configurations, cycle among several, have a keymap where each key sets
a different configurations, have a set of named configurations and be
prompted (with completion) for one of them, popup a hydra to choose a
configuration, etc. Since there are so many possible UIs and which to
use is mostly a matter of taste,
orderless does not provide any such
commands. But it's easy to write your own!
For example, say you want to use the keybinding
C-l to make all
components match literally. You could use the following code:
(defun my/match-components-literally () "Components match literally for the rest of the session." (interactive) (setq-local orderless-matching-styles '(orderless-literal) orderless-style-dispatchers nil)) (define-key minibuffer-local-completion-map (kbd "C-l") #'my/match-components-literally)
setq-local to assign to the configuration variables ensures the
values are only used for that minibuffer completion session.
Several excellent completion UIs exist for Emacs in third party packages. They do have a tendency to forsake standard Emacs APIs, so integration with them must be done on a case by case basis.
If you manage to use
orderless with a completion UI not listed here,
please file an issue or make a pull request so others can benefit from
your effort. The functions
orderless--component-regexps are likely to help with the
orderless from Ivy add this to your Ivy configuration:
(setq ivy-re-builders-alist '((t . orderless-ivy-re-builder)))
Recent versions of Selectrum default to using whatever completion
styles you have configured. If you stick with that default
configuration you can use
orderless just by adding it to
completion-styles. Alternatively, you can use this configuration:
(setq selectrum-refine-candidates-function #'orderless-filter) (setq selectrum-highlight-candidates-function #'orderless-highlight-matches)
If you use the above configuration, only the visible candidates are highlighted, which is a litte more efficient.
Company comes with a
company-capf backend that uses the
completion-at-point functions, which in turn use completion styles.
This means that the
company-capf backend will automatically use
orderless, no configuration necessary!
But there are a couple of points of discomfort:
Pressing SPC takes you out of completion, so with the default separator you are limited to one component, which is no fun. To fix this add a separator that is allowed to occur in identifiers, for example, for Emacs Lisp code you could use an ampersand:
(setq orderless-component-separator "[ &]")
The matching portions of candidates aren't highlighted. That's
company-capf is hard-coded to look for the
completions-common-part face, and it only use one face,
company-echo-common to highlight candidates.
So, while you can't get different faces for different components, you can at least get the matches highlighted in the sole available face with this configuration:
(defun just-one-face (fn &rest args) (let ((orderless-match-faces [completions-common-part])) (apply fn args))) (advice-add 'company-capf--candidates :around #'just-one-face)
(Aren't dynamically scoped variables and the advice system nifty?)
The well-known and hugely powerful completion frameworks Ivy and Helm
also provide for matching space-separated component regexps in any
order. In Ivy, this is done with the
In Helm, it is the default, called "multi pattern matching".
This package is significantly smaller than either of those because it solely defines a completion style, meant to be used with any completion UI supporting completion styles while both of those provide their own completion UI (and many other cool features!).
It is worth pointing out that Helm does provide its multi pattern matching as a completion style which could be used with default tab completion, Icomplete, Selectrum or other UIs supporting completion styles! (Ivy does not provide a completion style to my knowledge.) So, for example, Icomplete users could, instead of using this package, install Helm and configure Icomplete to use it as follows:
(require 'helm) (setq completion-styles '(helm)) (icomplete-mode)
(Of course, if you install Helm, you might as well use the Helm UI in
helm-mode rather than Icomplete.)
The prescient.el library also provides matching of space-separated
components in any order and it can be used with either the Selectrum
or Ivy completion UIs (it does not offer a completion-style that
could be used with Emacs' default completion UI or with Icomplete).
The components can be matched literally, as regexps, as initialisms or
in the flex style (called "fuzzy" in prescient). In addition to
prescient.el also supports sorting of candidates (
leaves that up to the candidate source and the completion UI).
An effect equivalent to matching multiple components in any order can
be achieved in completion frameworks that provide a way to restrict
further matching to the current list of candidates. If you use the
keybinding for restriction instead of
SPC to separate your components,
you get out of order matching!
icicle-apropos-complete-and-narrowcommand, bound to
S-SPC, to do it.
ido-restrict-to-matchesand binds it to
ivy-restrict-to-matches, bound to
S-SPC, so you can get the effect of out of order matching without using