# minad/corfu: A minimal completion popup for Emacs

> Corfu is an Emacs Lisp package that replaces Emacs' in-buffer completion presentation with a small popup. It provides candidate navigation, previews, sorting, history support and extensions, but deliberately leaves candidate generation to Emacs completion facilities and Capfs.

**minad/corfu** — :desert_island: corfu.el - COmpletion in Region FUnction

- Repository: https://github.com/minad/corfu
- Stars: 1,546 · Forks: 59
- Language: Emacs Lisp
- License: GPL-3.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/minad-corfu

## Corfu's split between completion sources and popup UI

Corfu solves the presentation problem in Emacs completion. Instead of accepting candidates through the ordinary in-buffer interface alone, it shows the current candidates in a popup below or above point. The package describes itself as the in-buffer counterpart to Vertico, which presents the minibuffer UI, so the distinction is specifically about where and how completion information appears while editing ordinary buffers.

The important boundary is that Corfu is not a completion data source. It hooks into `completion-in-region`, the Emacs facility that handles interaction with the user during completion. Candidates may come from commands such as `dabbrev-completion`, or from pluggable backends listed in `completion-at-point-functions`, commonly called Capfs. Many programming, text and shell major modes already implement a Capf. Corfu receives those candidates and supplies the popup, navigation behavior and related extensions around them.

That division makes Corfu suitable for Emacs users who already have useful completion infrastructure. It also means that a buffer with no suitable completion function may not provide useful candidates merely because Corfu is enabled. The separate Cape package is described as providing additional Capfs and completion utilities, which is the relevant distinction for users who need broader source coverage.

## The Corfu popup and transient completion keymap

Corfu's main interaction occurs through a small popup containing the current candidates. A scrollbar indicator communicates the size and position of the candidate list, while arrow keys move between entries. The popup can be summoned explicitly with `TAB`, even when automatic completion is not running. `TAB` inserts the current candidate, while `RET` selects it. The selected candidate can be previewed, and further input can automatically commit it by default.

The package uses a transient `corfu-map` while the popup is shown. This map remaps commands such as `move-beginning-of-line` and `move-end-of-line` to `corfu-prompt-beginning` and `corfu-prompt-end`. Navigation is handled by `corfu-next`, `corfu-previous`, `corfu-first`, `corfu-last` and scrolling commands. `M-TAB` invokes `corfu-expand`, `M-g` runs `corfu-info-location`, `M-h` runs `corfu-info-documentation`, and `M-SPC` inserts the configured separator. `C-g` quits, while `keyboard-escape-quit` resets Corfu.

Corfu also supports the Orderless completion style. Its filter string can contain arbitrary characters after inserting a space with `M-SPC`. Whether Corfu stops at a completion boundary, and what separator it uses, are controlled by `corfu-quit-at-boundary` and `corfu-separator`.

## Sorting, annotations and optional automatic completion

Candidate presentation is configurable rather than fixed. Corfu can sort by prefix, string length and alphabetically, with history-based sorting available as an optional behavior. The selected candidate is previewed through `corfu-preview-current`. By default, further input commits that candidate automatically, but the same variable can disable automatic commit and preview behavior. Other documented customization options include cycling with `corfu-cycle`, changing boundary behavior with `corfu-quit-at-boundary`, keeping the popup active without a match with `corfu-quit-no-match`, selecting the prompt with `corfu-preselect`, and choosing exact-match behavior with `corfu-on-exact-match`.

The popup also preserves information supplied by completion sources. Corfu supports candidate annotations through `annotation-function` and `affixation-function`, displays deprecated candidates with a crossed-out appearance, and allows external packages to provide icons through margin formatter functions. Its extension system covers quick keys, index keys, history sorting, documentation in the echo area, documentation in a popup and documentation in a separate buffer.

Automatic completion is disabled by default. This is a deliberate safety and interruption choice, not an absent feature. To enable it, the README says to set `corfu-auto` to `t`, locally or globally, before enabling `corfu-mode` or `global-corfu-mode`. The documentation specifically warns that completion in untrusted files can be vulnerable to arbitrary code execution, including code evaluation performed by `elisp-completion-at-point`.

## Installing Corfu through ELPA or MELPA

The README identifies ELPA and MELPA as the installation sources. In Emacs, use `package-install` with the package name, then activate the global minor mode. The documented commands are:

```bash
M-x package-install RET corfu RET
```

After installation, activate Corfu globally with:

```bash
M-x global-corfu-mode RET
```

The README says that manual completion can then be tried in an Elisp buffer, an Eshell buffer or a Shell buffer. Automatic completion remains disabled until `corfu-auto` is enabled, so the first use should be manual and deliberate.

For users who want to try customization, the README mentions `use-package` and the `corfu-*` variables. The following is the documented configuration excerpt, with the optional settings retained as shown:

```emacs-lisp
(use-package corfu
  ;; Optional customizations
  :custom
  (corfu-cycle t)
  (corfu-quit-at-boundary nil)
  (corfu-quit-no-match nil)
  (corfu-preview-current nil)
  (corfu-preselect 'prompt)
  (corfu-on-exact-match 'insert)
```

 The package is available from GNU ELPA and MELPA releases. No GitHub releases are listed for the repository.

## Child frames and the Emacs terminal constraint

Corfu relies on child frames to display its popup. The README states that this works for terminal Emacs on Emacs 31. For older Emacs versions, it points to the separate `corfu-terminal` package. This is a real platform constraint for users evaluating Corfu, especially users running terminal Emacs rather than a graphical Emacs process.

The popup is therefore not merely a text overlay inserted into the current buffer. Its placement above or below point depends on a separate frame mechanism. Users on older terminal Emacs versions need to account for the documented companion package, while users on Emacs 31 can use the compatibility stated in the README.

The repository also has no GitHub releases, so installation is not framed around release artifacts from GitHub. Maintenance status should instead be read from repository activity. The repository is not archived, and its last push was on 2026-10-14. That date establishes recent repository activity, but it does not by itself document upgrade procedures, compatibility across every Emacs release or the stability of each extension.

## Why Corfu differs from Vertico and other completion interfaces

Vertico is the direct comparison named by Corfu's README, but the two packages address different Emacs interaction surfaces. Vertico is described as the minibuffer UI, while Corfu is the in-buffer completion counterpart with a popup below or above point. Corfu is intended for completion while editing a buffer; it does not replace the minibuffer interface with its own candidate-generation system.

A second comparison is Cape, which is described as a separate package providing additional Capfs and completion utilities. Corfu focuses on the UI around candidates, while Cape addresses the availability of additional completion sources and utilities. That division matters when a mode has no Capf or when a language requires source-specific completion logic. Installing Corfu alone cannot create those backends.

Corfu may also be the wrong choice for users who prefer the standard Emacs completion presentation or need a completion engine that works independently of Capfs. It is better aligned with users who want an explicit popup, keyboard-driven selection and optional preview while retaining Emacs' existing completion infrastructure. The decision depends on the modes and Capfs already present, not on the size of Corfu's extension list.

## Conclusion

Adopt Corfu when you already use Emacs completion-capable modes and want a focused popup instead of the default in-buffer presentation. Do not adopt it as a standalone completion engine, since it supplies no backend of its own. Verify first that your major modes expose suitable Capfs, that child frames work in your Emacs environment, and that automatic completion is acceptable for the buffers you edit. The documented installation path is ELPA or MELPA, followed by `global-corfu-mode`; the repository has no GitHub releases, and its last push was on 2026-10-14.

## FAQ

### How do I install and activate Corfu in Emacs?

Install the `corfu` package from ELPA or MELPA using `M-x package-install RET corfu RET`, then activate the global minor mode with `M-x global-corfu-mode RET`. Automatic completion is disabled by default.

### Does Corfu provide its own completion backends?

No. Corfu hooks into `completion-in-region` and uses candidates from commands such as `dabbrev-completion` or Capfs listed in `completion-at-point-functions`. Additional Capfs and completion utilities are available through the separate Cape package.

### How can I make Corfu complete automatically?

Set `corfu-auto` to `t`, locally or globally, before enabling `corfu-mode` or `global-corfu-mode`. The README warns that automatic completion in untrusted files can execute arbitrary code through completion mechanisms such as `elisp-completion-at-point`.

## Sources

- [Issues](https://github.com/minad/corfu/issues)
- [License: GPL-3.0](https://github.com/minad/corfu/blob/main/LICENSE)
- [minad/corfu on GitHub](https://github.com/minad/corfu)
- [README](https://github.com/minad/corfu/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/minad-corfu