Emacs Docs

Appearance

Fine-tuning of individual commands ​

NOTE: Consult supports fine-grained customization of individual commands. This configuration feature exists for experienced users with special requirements. There is the Consult wiki, where we collect further configuration examples.

Commands and buffer sources allow flexible, individual customization by using the ‘consult-customize’ macro. You can override any option passed to the internal ‘consult--read’ API. Note that since ‘consult--read’ is part of the internal API, options could be removed, replaced or renamed in future versions of the package.

Useful options are:

  • ‘:prompt’ set the prompt string
  • ‘:preview-key’ set the preview key, default is ‘consult-preview-key’
  • ‘:initial’ set the initial input
  • ‘:initial-narrow’ set the initial narrow key
  • ‘:default’ set the default value
  • ‘:history’ set the history variable symbol
  • ‘:add-history’ add items to the future history, for example symbol at point
  • ‘:sort’ enable or disable sorting
  • ‘:group’ set to nil to disable candidate grouping and titles.
  • ‘:inherit-input-method’ set to non-nil to inherit the input method.
emacs-lisp
(consult-customize
 ;; Disable preview for `consult-theme' completely.
 consult-theme :preview-key nil
 ;; Set preview for `consult-buffer' to key `M-.'
 consult-buffer :preview-key "M-."
 ;; For `consult-line' change the prompt and specify multiple preview
 ;; keybindings. Note that you should bind <S-up> and <S-down> in the
 ;; `minibuffer-local-completion-map' or `vertico-map' to the commands which
 ;; select the previous or next candidate.
 consult-line :prompt "Search: "
 :preview-key '("S-<down>" "S-<up>"))

The configuration values are evaluated at runtime, just before the completion session is started. Therefore you can use for example ‘thing-at-point’ to adjust the initial input or the future history.

emacs-lisp
(consult-customize
 consult-line
 :add-history (seq-some #'thing-at-point '(region symbol)))

(defalias 'consult-line-thing-at-point 'consult-line)

(consult-customize
 consult-line-thing-at-point
 :initial (thing-at-point 'symbol))

Generally it is possible to modify commands for your individual needs by the following techniques:

  1. Use ‘consult-customize’ in order to change the command or source settings.
  2. Create your own wrapper function which passes modified arguments to the Consult functions.
  3. Create your own buffer multi sources for ‘consult-buffer’.
  4. Create advices to modify some internal behavior.
  5. Write or propose a patch.