Emacs Docs

Appearance

Live previews ​

Some Consult commands support live previews. For example when you scroll through the items of ‘consult-line’, the buffer will scroll to the corresponding position. It is possible to jump back and forth between the minibuffer and the buffer to perform recursive editing while the search is ongoing.

Consult enables previews by default. You can disable them by adjusting the ‘consult-preview-key’ variable. Furthermore it is possible to specify keybindings which trigger the preview manually as shown in the example configuration. The default setting of ‘consult-preview-key’ is ‘any’ which means that Consult triggers the preview immediately on any key press when the selected candidate changes. You can configure each command individually with its own ‘:preview-key’. The following settings are possible:

  • Automatic and immediate ‘'any’
  • Automatic and delayed ‘(list :debounce 0.5 'any)’
  • Manual and immediate ‘"M-."’
  • Manual and delayed ‘(list :debounce 0.5 "M-.")’
  • Disabled ‘nil’

A safe recommendation is to leave automatic immediate previews enabled in general and disable the automatic preview only for commands where the preview may be expensive due to file loading. Internally, Consult uses the value of ‘this-command’ to determine the ‘:preview-key’ customized. This means that if you wrap a ‘consult-*’ command within your own function or command, you will also need to add the name of your custom command to the ‘consult-customize’ call in order for it to be considered.

emacs-lisp
(consult-customize
 consult-ripgrep consult-git-grep consult-grep consult-man
 consult-bookmark consult-recent-file consult-xref
 consult-source-bookmark consult-source-file-register
 consult-source-recent-file consult-source-project-recent-file
 :preview-key '(:debounce 0.4 any)) ;; Option 1: Delay preview
 ;; :preview-key "M-."              ;; Option 2: Manual preview

In this case one may wonder what the difference is between using an Embark action on the current candidate in comparison to a manually triggered preview. The main difference is that the files opened by manual preview are closed again after the completion session. During preview some functionality is disabled to improve the performance, see for example the customization variables ‘consult-preview-variables’ and ‘consult-preview-allowed-hooks’. Only hooks listed in ‘consult-preview-allowed-hooks’ are executed. This variable applies to ‘find-file-hook’, ‘change-major-mode-hook’ and mode hooks, e.g., ‘prog-mode-hook’. In order to enable additional font locking during preview, add the corresponding hooks to the allow list. The following code demonstrates this for org-modern and hl-todo.

emacs-lisp
;; local modes added to prog-mode hooks
(add-to-list 'consult-preview-allowed-hooks 'hl-todo-mode)
(add-to-list 'consult-preview-allowed-hooks 'elide-head-mode)
;; enabled global modes
(add-to-list 'consult-preview-allowed-hooks 'global-org-modern-mode)
(add-to-list 'consult-preview-allowed-hooks 'global-hl-todo-mode)

Files larger than ‘consult-preview-partial-size’ are previewed partially. Delaying the preview is also useful for ‘consult-theme’, since the theme preview is slow. The delay results in a smoother UI experience.

emacs-lisp
;; Preview on any key press, but delay 0.5s
(consult-customize consult-theme :preview-key '(:debounce 0.5 any))
;; Preview immediately on M-., on up/down after 0.5s, on any other key after 1s
(consult-customize consult-theme
                   :preview-key
                   '("M-."
                     :debounce 0.5 "<up>" "<down>"
                     :debounce 1 any))