Corfu

#+title: corfu.el - COmpletion in Region FUnction #+author: Daniel Mendler #+language: en #+export_file_name: corfu.texi #+texinfo_dir_category: Emacs misc features #+texinfo_dir_title: Corfu: (corfu). #+texinfo_dir_desc: COmpletion in Region FUnction

#+html: <a href="https://www.gnu.org/software/emacs/"><img alt="GNU Emacs" src="https://github.com/minad/corfu/blob/screenshots/emacs.svg?raw=true"/></a> #+html: <a href="https://melpa.org/#/corfu"><img alt="MELPA" src="https://melpa.org/packages/corfu-badge.svg"/></a> #+html: <a href="https://stable.melpa.org/#/corfu"><img alt="MELPA Stable" src="https://stable.melpa.org/packages/corfu-badge.svg"/></a>

Corfu enhances in-buffer completion with a small completion popup. The current candidates are shown in a popup below or above the point, and can be selected by moving up and down. Corfu is the minimalistic in-buffer completion counterpart of the [[https://github.com/minad/vertico][Vertico]] minibuffer UI.

Corfu is a small package, which relies on the Emacs completion facilities and concentrates on providing a polished completion UI. In-buffer completion UIs in Emacs can hook into ~completion-in-region~, which implements the interaction with the user. Completions at point are either provided by commands like ~dabbrev-completion~ or by pluggable backends (~completion-at-point-functions~, Capfs) and are then passed to ~completion-in-region~. Many programming, text and shell major modes implement a Capf. Corfu does not include its own completion backends. The Emacs built-in Capfs and the Capfs provided by third-party programming language packages are often sufficient. Additional Capfs and completion utilities are provided by the separate [[https://github.com/minad/cape][Cape]] package.

NOTE: Corfu relies on child frames to show the popup. On Emacs 31 this works for terminal Emacs. Use the [[https://codeberg.org/akib/emacs-corfu-terminal][corfu-terminal]] package on older Emacs versions.

#+html: <img src="https://github.com/minad/corfu/blob/screenshots/light.png?raw=true">

#+html: <img src="https://github.com/minad/corfu/blob/screenshots/dark.png?raw=true">

#+html: <img src="https://github.com/minad/corfu/blob/screenshots/popupinfo-light.png?raw=true">

#+html: <img src="https://github.com/minad/corfu/blob/screenshots/popupinfo-dark.png?raw=true">

#+toc: headlines 8

• Features

• Auto-completion with timer or character trigger (/off/ by default).
• Popup display with scrollbar indicator and arrow key navigation.
• The popup can be summoned explicitly by pressing =TAB= at any time.
• The current candidate is inserted with =TAB= and selected with =RET=.
• Sorting by prefix, string length and alphabetically, optionally by history.
• The selected candidate is previewed (configurable via ~corfu-preview-current~).
• The selected candidate is automatically committed on further input by default. (configurable via ~corfu-preview-current~).
• Supports the [[https://github.com/oantolin/orderless][Orderless]] completion style. The filter string can contain arbitrary characters, after inserting a space via =M-SPC= (configurable via ~corfu-quit-at-boundary~ and ~corfu-separator~).
• Lazy candidate highlighting for performance.
• Support for candidate annotations (=annotation-function=, =affixation-function=).
• Deprecated candidates are displayed as crossed out.
• Icons are provided by external packages via margin formatter functions.
• Rich set of extensions: Quick keys, index keys, sorting by history, documentation in echo area, popup or separate buffer.

• Installation

Corfu is available from MELPA and can be installed via =M-x package-install RET corfu RET=. After installation, activate the global minor mode with =M-x global-corfu-mode RET=. For completion press =M-TAB= (or =TAB=) within a buffer. Auto completion is disabled by default for safety and unobtrusiveness.

• Key bindings

Corfu uses a transient keymap ~corfu-map~ which is active while the popup is shown. The keymap defines the following remappings of fundamental commands and bindings:

| Binding/Remapping | Corfu command | |--------------------------+--------------------------| | ~move-beginning-of-line~ | ~corfu-prompt-beginning~ | | ~move-end-of-line~ | ~corfu-prompt-end~ | | ~beginning-of-buffer~ | ~corfu-first~ | | ~end-of-buffer~ | ~corfu-last~ | | ~scroll-down-command~ | ~corfu-scroll-down~ | | ~scroll-up-command~ | ~corfu-scroll-up~ | | ~next-line~, =down=, =M-n= | ~corfu-next~ | | ~previous-line~, =up=, =M-p= | ~corfu-previous~ | | ~completion-at-point~, =TAB= | ~corfu-complete~ | | =M-TAB= | ~corfu-expand~ | | =RET= | ~corfu-insert~ | | =M-g= | ~corfu-info-location~ | | =M-h= | ~corfu-info-documentation~ | | =M-SPC= | ~corfu-insert-separator~ | | =C-g= | ~corfu-quit~ | | ~keyboard-escape-quit~ | ~corfu-reset~ |

• Configuration

In order to configure Corfu and other packages in your init.el, you may want to use ~use-package~. Corfu is flexibly customizable via ~corfu-*~ customization variables, such that you can adapt it precisely to your requirements. However in order to quickly try out the Corfu completion package, it should be sufficient to activate ~global-corfu-mode~. You can experiment with manual completion for example in an Elisp buffer or in an Eshell or Shell buffer.

Auto completion is disabled by default in Corfu. Note that completion can be vulnerable to arbitrary code execution in untrusted files. In particular the ~elisp-completion-at-point~ completion function performs macro expansion and code evaluation. Auto completion can be enabled by setting ~corfu-auto~ to t locally or globally before enabling the local ~corfu-mode~ or the ~global-corfu-mode~.

Here is an example configuration:

#+begin_src emacs-lisp (use-package corfu ;; Optional customizations ;; :custom ;; (corfu-cycle t) ;; Enable cycling for `corfu-next/previous' ;; (corfu-quit-at-boundary nil) ;; Never quit at completion boundary ;; (corfu-quit-no-match nil) ;; Never quit, even if there is no match ;; (corfu-preview-current nil) ;; Disable current candidate preview ;; (corfu-preselect 'prompt) ;; Preselect the prompt ;; (corfu-on-exact-match 'insert) ;; Configure handling of exact matches

;; Enable Corfu only for certain modes. See also `global-corfu-modes'. ;; :hook ((prog-mode . corfu-mode) ;; (shell-mode . corfu-mode) ;; (eshell-mode . corfu-mode))

:init

;; Recommended: Enable Corfu globally. Recommended since many modes provide ;; Capfs and Dabbrev can be used globally (M-/). See also the customization ;; variable `global-corfu-modes' to exclude certain modes. (global-corfu-mode)

;; Enable optional extension modes: ;; (corfu-history-mode) ;; (corfu-popupinfo-mode) )

;; A few more useful configurations... (use-package emacs :custom ;; TAB cycle if there are only few candidates ;; (completion-cycle-threshold 3)

;; Enable indentation+completion using the TAB key. ;; `completion-at-point' is often bound to M-TAB. (tab-always-indent 'complete)

;; Emacs 30 and newer: Disable Ispell completion function. ;; Try `cape-dict' as an alternative. (text-mode-ispell-word-completion nil)

;; Hide commands in M-x which do not apply to the current mode. Corfu ;; commands are hidden, since they are not used via M-x. This setting is ;; useful beyond Corfu. (read-extended-command-predicate #'command-completion-default-include-p)) #+end_src

Dabbrev completion is based on =completion-in-region= and can be used with Corfu. You may want to swap the =dabbrev-completion= with the =dabbrev-expand= key for easier access, if you prefer completion. Also take a look at the =cape-dabbrev= completion at point function provided by my [[https://github.com/minad/cape][Cape]] package.

#+begin_src emacs-lisp ;; Use Dabbrev with Corfu! (use-package dabbrev ;; Swap M-/ and C-M-/ :bind (("M-/" . dabbrev-completion) ("C-M-/" . dabbrev-expand)) :config (add-to-list 'dabbrev-ignored-buffer-regexps "\` ") (add-to-list 'dabbrev-ignored-buffer-modes 'authinfo-mode) (add-to-list 'dabbrev-ignored-buffer-modes 'doc-view-mode) (add-to-list 'dabbrev-ignored-buffer-modes 'pdf-view-mode) (add-to-list 'dabbrev-ignored-buffer-modes 'tags-table-mode)) #+end_src

If you start to configure Corfu more thoroughly, I recommend to give the Orderless completion style a try for filtering. Orderless completion offers more flexible filtering than the default completion styles. Note that Orderless is not a necessity; Corfu can be used just as well with the default completion styles.

#+begin_src emacs-lisp ;; Optionally use the `orderless' completion style. (use-package orderless :custom ;; (orderless-style-dispatchers '(orderless-affix-dispatch)) ;; (orderless-component-separator #'orderless-escapable-split-on-space) (completion-styles '(orderless basic)) (completion-category-overrides '((file (styles partial-completion)))) (completion-category-defaults nil) ;; Disable defaults, use our settings (completion-pcm-leading-wildcard t)) ;; Emacs 31: partial-completion behaves like substring #+end_src

The =basic= completion style is specified as fallback in addition to =orderless= in order to ensure that completion commands which rely on dynamic completion tables, e.g., ~completion-table-dynamic~ or ~completion-table-in-turn~, work correctly. Additionally enable =partial-completion= for file path expansion. =partial-completion= is important for file wildcard support. Multiple files can be opened at once with =find-file= if you enter a wildcard. You may also give the =initials= completion s