You are viewing the documentation for the develop branch. The documentation for the release version is here .

Table of Contents

Auto-completion layer

Table of ContentsClose

1. Description

This layer adds auto-completion to all supported language layers.

1.1. Features:

2. Install

To use this configuration layer, add it to your ~/.spacemacs. You will need to add auto-completion to the existing dotspacemacs-configuration-layers list in this file.

As this is a support layer you will also have to install at least one supported language layer for it to have any effect.

3. Configuration

3.1. Key bindings

You can customize the user experience of auto-completion with the following layer variables:

  1. auto-completion-return-key-behavior set the action to perform when the RET key is pressed, the possible values are:
    • complete completes with the current selection
    • nil does nothing
  2. auto-completion-tab-key-behavior set the action to perform when the TAB key is pressed, the possible values are:
    • complete completes with the current selection
    • cycle completes the common prefix and cycle between candidates
    • nil does nothing
  3. auto-completion-complete-with-key-sequence is a string of two characters denoting a key sequence that will perform a complete action if the sequence has been entered quickly enough. If its value is nil then the feature is disabled.
  4. auto-completion-complete-with-key-sequence-delay is the number of seconds to wait for the auto-completion key sequence to be entered. The default value is 0.1 seconds.
  5. auto-completion-idle-delay is the number of seconds to wait before suggesting completions. The default value is 0.2 seconds. Set to nil to disable automatic suggestions (the TAB key will still perform completion). Set to 0.0 for optimal results with lsp mode.
  6. auto-completion-minimum-prefix-length is the minimum number of characters which must be entered before completions will be suggested automatically. Set to 1 for optimal results with lsp mode.

The default configuration of the layer is:

(setq-default dotspacemacs-configuration-layers '(
  (auto-completion :variables
                   auto-completion-return-key-behavior 'complete
                   auto-completion-tab-key-behavior 'cycle
                   auto-completion-complete-with-key-sequence nil
                   auto-completion-complete-with-key-sequence-delay 0.1
                   auto-completion-minimum-prefix-length 2
                   auto-completion-idle-delay 0.2
                   auto-completion-private-snippets-directory nil
                   auto-completion-enable-snippets-in-popup nil
                   auto-completion-enable-help-tooltip nil
                   auto-completion-use-company-box nil
                   auto-completion-enable-sort-by-usage nil)))

jk is a good candidate for auto-completion-complete-with-key-sequence if you don't use it already.

3.2. Snippets directories

The following directories are added by default:

  • ~/.emacs.d/elpa/yasnippet-xxxxx/snippets
  • ~/.emacs.d/layers/auto-completion/snippets
  • ~/.emacs.d/private/snippets (conditional to the value of auto-completion-private-snippets-directory)
  • ~/.spacemacs.d/snippets (conditional to the existence of ~/.spacemacs.d directory)

You can provide additional directories by setting the variable auto-completion-private-snippets-directory which can either take a single path as string or a list of paths.

If its value is nil then the path ~/.emacs.d/private/snippets is used.

3.3. Show snippets in auto-completion popup

By default, snippets are not shown in the auto-completion popup. To show them in the popup, set the variable auto-completion-enable-snippets-in-popup to t.

(setq-default dotspacemacs-configuration-layers
              '((auto-completion :variables
                                 auto-completion-enable-snippets-in-popup t)))

3.4. Tooltips

To enable automatic docstring tooltips set auto-completion-enable-help-tooltip to t.

(setq-default dotspacemacs-configuration-layers
  '((auto-completion :variables
                    auto-completion-enable-help-tooltip t)))

To enable manual non-automatic invocation of docstring tooltips, set it to manual. The tooltip can be invoked manually by pressing M-h.

(setq-default dotspacemacs-configuration-layers
  '((auto-completion :variables
                    auto-completion-enable-help-tooltip 'manual)))

However the tooltip may overlap on text on macOS, you can use company-box or company-posframe on by setting auto-completion-use-company-box or auto-completion-use-company-posframe to t, respectively.

3.5. Sort results by usage

To enable sorting auto-completion results by their usage frequency set auto-completion-enable-sort-by-usage to t. This feature is provided by the company-statistics package when company is used. The variable has no effect when auto-complete is used.

Beware: Sorting completion results is often done already by the completion backend, doing it again in company may degrate performance.

(setq-default dotspacemacs-configuration-layers
  '((auto-completion :variables
                    auto-completion-enable-sort-by-usage t)))

3.6. Disable auto-completion in specific layers

See general documentation on how to disable a layer for specific layers.

3.7. Enable company globally

It can be done by adding (global-company-mode) in the dotspacemacs/user-config function of your dotfile. But it is not recommended to do so, you should instead open an issue to ask for auto-completion support for the major-modes where it is missing.

If you choose to use (global-company-mode) then you would lose some advantages provided by the layer system like disabling auto-completion for specific layers.

3.8. Replacing company by auto-complete

You can disable company by adding it to the dotspacemacs-excluded-packages variable, then you are free to enable auto-complete globally.

3.9. Add auto-completion in a layer

Here is an example to add company auto-completion to python buffers via the package company-anaconda.

In the file packages.el of the python layer:

;; Add the relevant packages to the layer
;; here it is `company-anaconda'
(setq python-packages
    (company-anaconda :toggle (configuration-layer/package-used-p 'company))

(defun python/init-company-anaconda ()
  (use-package company-anaconda
    :defer t
       :backends company-anaconda
       :modes python-mode)))

3.10. Completion back ends

Many spacemacs layers (e.g., python, html, haskell) configure company mode backends to provide mode-specific completion. These modes will include completion backends specified in the spacemacs-default-company-backends variable. The defaults should work well, but you can configure this variable in your .spacemacs file with (e.g.)

 '((auto-completion :variables
                    spacemacs-default-company-backends '(company-files company-capf))))

3.11. Improved faces

For nicer-looking faces, try adding the following to `custom-set-faces` in your dotspacemacs file.

   ((t (:inherit company-tooltip :weight bold :underline nil))))
   ((t (:inherit company-tooltip-selection :weight bold :underline nil)))))

4. Key bindings

4.1. Company

Key binding Description
C-d open minibuffer with documentation of thing at point in company dropdown
C-/ show candidates in Helm or Ivy (for fuzzy searching)
C-M-/ filter the company dropdown menu
M-h show current candidate's documentation in a tooltip (requires auto-completion-enable-help-tooltip)

Vim Style:

Key binding Description
C-j (vim style) go down in company dropdown menu
C-k (vim style) go up in company dropdown menu
C-l (vim style) complete selection

Emacs style:

Key binding Description
C-n (emacs style) go down in company dropdown menu
C-p (emacs style) go up in company dropdown menu

4.2. Auto-complete

Key binding Description
C-j select next candidate
C-k select previous candidate
TAB expand selection or select next candidate
S-TAB select previous candidate
RET complete word, if word is already completed insert a carriage return

4.3. Yasnippet

Key binding Description
M-/ Expand a snippet if text before point is a prefix of a snippet
SPC i s List all current yasnippets for inserting

4.4. Auto-yasnippet

Key binding Description
SPC i S c create a snippet from an active region
SPC i S e Expand the snippet just created with SPC i y
SPC i S w Write the snippet inside private/snippets directory for future sessions

Author: root

Created: 2022-05-24 Tue 11:51