Emacs Docs

Appearance

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:

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-mouse-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))

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 Cape package.

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))

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.

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

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 style a try.

See also the Corfu Wiki and the Cape manual for additional Capf configuration tips. For more general documentation read the chapter about completion in the Emacs manual. If you want to create your own Capfs, you can find documentation about completion in the Elisp manual.