Search:

Completion With Corfu

  • Emacs
  • Elisp
  • Programming

When I first started using Emacs, I primarily used Company as my completion framework. Company works quite well, and despite using it's own completion system it seems to work well with a lot of other packages. Later on, when I read about Corfu, I initially thought it wasn't for me due to it's focus on simplicity. I was wrong- Corfu is pretty damn great!

If you've read my Emacs config post you might have seen my Corfu setup:

(use-package corfu
  :init
  (global-corfu-mode)
  (corfu-popupinfo-mode)
  (corfu-indexed-mode)
  :config
  (setopt corfu-cycle t
          corfu-auto t
          corfu-auto-delay 0.0
          corfu-preselect 'prompt
          corfu-auto-prefix 2
          corfu-quit-no-match 'separator)
  :bind (:map corfu-map
              ("<tab>" . 'corfu-next)
              ("<backtab>" . 'corfu-previous)))

But I didn't go through it in detail, so let's do that now. This configuration uses the use-package macro, which you are likely already familiar with if you're a regular user of Emacs, but the TL;DR is that it's a macro to help manage packages in your Emacs configuration in a more declarative manner. It has a couple different "sections" to it, most (if not all) are optional. I'm going to explain things to the best of my ability, but be warned I may get some details wrong.

Init

First up, we using the init section for Elisp we want evaluated just before the package is loaded. I'm not 100% certain why I initially put these into the init section, but we're here now so I'm just going to roll with it.

(use-package corfu
  :init
  (global-corfu-mode)
  (corfu-popupinfo-mode)
  (corfu-indexed-mode)
  ;; ...

It's doing three things here:

  • Activating the global-corfu-mode, to ensure that Corfu is enabled wherever possible.
  • Activating the corfu-popupinfo-mode, which enables a pop-up info box that appears next to the completion candidate.
  • Activating the corfu-indexed-mode, which shows numbers next to each completion candidate. I believe you can set up some form of keymaps to quickly access completion candidates via this mode, but I'm not sure how that works.

Config

Next we have the config section, which is evaluated just after the package is loaded. Though it should be noted that when exactly it is evaluated can differ depending on the loading mechanism of the package.

  ;; ...
  :config
  (setopt corfu-cycle t
          corfu-auto t
          corfu-auto-delay 0.0
          corfu-preselect 'prompt
          corfu-auto-prefix 2
          corfu-quit-no-match 'separator)
  ;; ...

Here I use the setopt macro (my beloved) to set some of the default options I want Corfu to use:

  • corfu-cycle t: This enables cycling (AKA wrapping) completion candidates when you reach the that start/end of the completion list, and keep going. For example if you reach the end of the list and go down one more, it'll wrap around to the start of the list.
  • corfu-auto t: This tells Corfu the automatically show the completion menu whenever possible, without having to manually input a keymap for it.
  • corfu-auto-delay: This sets the delay needed between an input for the completion menu to show, if corfu-auto is enabled.
  • corfu-preselect 'prompt: This sets what Corfu will preselect by default. Setting it to 'prompt, Corfu will select the inputted text by default, so if you insert the candidate without changing it, no extra text will be inserted.
  • corfu-auto-prefix 2: This sets the prefix (how many characters need to be inputted) before the completion menu with show (if corfu-auto is enabled).
  • corfu-quit-no-match 'separator: This ensures that the Corfu will automatically quit if no matching candidate is found. Setting it to 'separator ensures that the menu will stay if there is no match and the corfu-separator character has been inserted.

Bind

  ;; ...
  :bind (:map corfu-map
              ("<tab>" . 'corfu-next)
              ("<backtab>" . 'corfu-previous)))

The bind section allows you to set up the package's keymaps from the use-package macro. I like to be able to cycle completion candidates via both C-n/C-p and <tab>/<backtab> (AKA shift+tab).

Orderless

There is one slight problem with this setup, and that is that it has very strict ordering. If you had a function named example_function, and you tried to complete by typing ample, it likely wouldn't work. That's where Orderless comes in. Orderless is another completion package which allows the completion engine to match candidates outside of a rigid order. Just like Corfu, we can use the use-package macro to set it up- there is an example of which in the linked page above.