Emacs: icomplete, Name Completion

By Xah Lee. Date: . Last updated: .

This page is for Emacs 28 (Released 2022-04) or later.

What is icomplete-mode

icomplete-mode enhances emacs's name completion when in minibuffer prompts.

icomplete does completion for any command that prompts for a list of choices, such as opening a file, switch buffer, calling a command by name.

Examples of commands that icomplete has effect:

Alt+x icomplete-mode

Turn on or off enhanced completion in minibuffer.

  • Press Tab to complete.
  • press Ctrl+j to select current choice and submit.
  • press Enter to submit what's in minibuffer.
emacs 29 icomplete mode 2023-08-24 rWGf
emacs 29 icomplete mode 2023-08-24 rWGf


Alt+x icomplete-vertical-mode
  • Activates icomplete-mode
  • Change settings to show choices vertically.
  • Call again to toggle vertical display to horizontal.

icomplete-vertical-mode is new in Emacs 28 (Released 2022-04)

emacs 29 icomplete vertical mode 2023-08-24
emacs 29 icomplete vertical mode 2023-08-24

icomplete keys

Complete what you typed.
Complete up to a word.
Use what you typed so far.
Use first choice and exit.
complete backward
complete forward

Completion Styles

you can setup many different completion styles.

here are different styles, from Completion Styles (Emacs Manual)

  • A matching completion alternative must have the same beginning as the text in the minibuffer before point.
  • Furthermore, if there is any text in the minibuffer after point, the rest of the completion alternative must contain that text as a substring.
  • This aggressive completion style divides the minibuffer text into words separated by hyphens or spaces, and completes each word separately.
  • (For example, when completing command names, em-l-m completes to emacs-lisp-mode.)
  • Furthermore, a ‘*’ in the minibuffer text is treated as a “wildcard”—it matches any string of characters at the corresponding position in the completion alternative.
  • similar to basic, except that it ignores the text in the minibuffer after point.
  • A matching completion alternative must contain the text in the minibuffer before point, and the text in the minibuffer after point, as substrings (in that same order).
  • Thus, if the text in the minibuffer is foobar, with point between foo and bar, that matches AfooBbarC, where A, B, and C can be any string including the empty string.

if you typed abc it is matched against *a*b*c* where * are any char or no char.


lch matches list-command-history

Setup completion-styles

variable. List of completion styles to use. The available styles are listed in completion-styles-alist .
;; examples of setting completion styles

;; use flex match.
(setq completion-styles '(flex))

;; default in emacs 29
(setq completion-styles '(basic partial-completion emacs22))

Icomplete Mode Setup

I recommend just turn on icomplete-vertical-mode and set flex match.

Put this in your Emacs Init File:

(when (not (version< emacs-version "28.1"))
    ;; emacs 28.1 or later. use icomplete-vertical-mode and set flex match
    (setq completion-styles '(flex))
    (icomplete-vertical-mode 1)))
    (version< emacs-version "28.1")
    ;; use ido mode for flex matching, and make it display vertical
      ;; make buffer switch command do suggestions, also for find-file command
      (require 'ido)
      (ido-mode 1)
      ;; show choices vertically
      (setf (nth 2 ido-decorations) "\n")
      ;; show any name that has the chars you typed
      (setq ido-enable-flex-matching t)
      ;; use current pane for newly opened file
      (setq ido-default-file-method 'selected-window)
      ;; use current pane for newly switched buffer
      (setq ido-default-buffer-method 'selected-window))
      ;; minibuffer enhanced completion icomplete
      (require 'icomplete)
      (icomplete-mode 1)
      ;; show choices vertically
      (setq icomplete-separator "\n")
      (setq icomplete-hide-common-prefix nil)
      (setq icomplete-in-buffer t)
      (define-key icomplete-minibuffer-map (kbd "<right>") 'icomplete-forward-completions)
      (define-key icomplete-minibuffer-map (kbd "<left>") 'icomplete-backward-completions))))

History of Icomplete Mode

icomplete is originally written by Ken Manheimer, first released in 1993. (Ken Manheimer's home page: http://myriadicity.net/ • [2014-06-11 https://twitter.com/myriadicity ] )

Emacs Name Completion