Emacs Docs

Appearance

Multiple sources ​

Multiple static and asynchronous candidate sources can be combined. This feature is used by the ‘consult-buffer’ command to present buffer-like candidates in a single menu for quick access. By default ‘consult-buffer’ includes buffers, bookmarks, recent files and project-specific buffers and files. The ‘consult-buffer-sources’ variable configures the list of sources. Arbitrary custom sources can be added to this list.

As an example, the bookmark source is defined as follows:

emacs-lisp
(defvar consult-source-bookmark
  `(:name     "Bookmark"
    :narrow   ?m
    :category bookmark
    :face     consult-bookmark
    :history  bookmark-history
    :items    ,#'bookmark-all-names
    :action   ,#'consult--bookmark-action))

Either the ‘:items’ or the ‘:async’ source field is required:

  • ‘:items’ List of strings to select from or function returning list of strings. The strings can carry metadata in text properties, which is then available to the ‘:annotate’, ‘:action’ and ‘:state’ functions. The list can also consist of pairs, with the string in the ‘car’ used for display and the ‘cdr’ the actual candidate.
  • ‘:async’ Alternative to ‘:items’ for asynchronous sources. See the docstring for details.

Optional source fields:

  • ‘:name’ Name of the source, used for narrowing, group titles and annotations.
  • ‘:narrow’ Narrowing character, ‘(char . string)’ pair or list of pairs.
  • ‘:category’ Completion category.
  • ‘:preview-key’ Preview key or keys which trigger preview.
  • ‘:enabled’ Function which must return t if the source is enabled.
  • ‘:hidden’ When t candidates of this source are hidden by default.
  • ‘:face’ Face used for highlighting the candidates.
  • ‘:annotate’ Annotation function called for each candidate, returns string.
  • ‘:history’ Name of history variable to add selected candidate.
  • ‘:default’ Must be t if the first item of the source is the default value.
  • ‘:action’ Function called with the selected candidate.
  • ‘:new’ Function called with new candidate name, only if ‘:require-match’ is nil.
  • ‘:state’ State constructor for the source, must return the state function.
  • Other source fields can be added specifically to the use case.

The ‘:state’ and ‘:action’ fields of the sources deserve a longer explanation. The ‘:action’ function takes a single argument and is only called after selection with the selected candidate, if the selection has not been aborted. This functionality is provided for convenience and easy definition of sources. The ‘:state’ field is more general. The ‘:state’ function is a constructor function without arguments, which can perform some setup necessary for the preview. It must return a closure which takes an ACTION and a CANDIDATE argument. See the docstring of ‘consult--with-preview’ for more details about the ACTION argument.

By default, ‘consult-buffer’ previews buffers, bookmarks and files. Loading recent files or bookmarks can result in expensive operations. However it is possible to configure a manual preview as follows.

emacs-lisp
(consult-customize
 consult-source-bookmark consult-source-file-register
 consult-source-recent-file consult-source-project-recent-file
 :preview-key "M-.")

Sources can be added directly to the ‘consult-buffer-source’ list for convenience. For example, the following source lists all Org buffers and lets you create new ones.

emacs-lisp
(defvar org-source
  (list :name     "Org Buffer"
        :category 'buffer
        :narrow   ?o
        :face     'consult-buffer
        :history  'buffer-name-history
        :state    #'consult--buffer-state
        :new
        (lambda (name)
          (with-current-buffer (get-buffer-create name)
            (insert "#+title: " name "\n\n")
            (org-mode)
            (consult--buffer-action (current-buffer))))
        :items
        (lambda ()
          (consult--buffer-query :mode 'org-mode :as #'consult--buffer-pair))))

(add-to-list 'consult-buffer-sources 'org-source 'append)

One can create similar sources for other major modes. See the Consult wiki for many additional source examples. See also the documentation of ‘consult-buffer’ and of the internal ‘consult--multi’ API. The function ‘consult--multi’ can be used to create new multi-source commands.