Narrowing and grouping

Consult has special support for candidate groups. If the completion UI supports the grouping functionality, the UI separates the groups with thin lines and shows group titles. Grouping is useful if the list of candidates consists of candidates of multiple types or candidates from multiple sources, like the ‘consult-buffer’ command, which shows both buffers and recently opened files. Note that you can disable the group titles by setting the ‘:group’ property of the corresponding command to nil using the ‘consult-customize’ macro.

By entering a narrowing prefix or by pressing a narrowing key it is possible to restrict the completion candidates to a certain candidate group. When you use the ‘consult-buffer’ command, you can enter the prefix ‘b SPC’ to restrict list of candidates to buffers only. If you press ‘DEL’ afterwards, the full candidate list will be shown again. Furthermore a narrowing prefix key and a widening key can be configured which can be pressed to achieve the same effect, see the configuration variables ‘consult-narrow-key’ and ‘consult-widen-key’.

After pressing ‘consult-narrow-key’, the possible narrowing keys can be shown by pressing ‘C-h’. When pressing ‘C-h’ after some prefix key, the ‘prefix-help-command’ is invoked, which shows the keybinding help window by default. As a more compact alternative, there is the ‘consult-narrow-help’ command which can be bound to a key, for example ‘?’ or ‘C-h’ in the ‘consult-narrow-map’, as shown in the example configuration. If which-key is installed, the narrowing keys are automatically shown in the which-key window after pressing the ‘consult-narrow-key’.