Installation ¶

Company package is distributed via commonly used package archives in a form of both stable and development releases. To install Company, type M-x package-install RET company RET.

For more details on Emacs package archives, see (emacs)Packages.

Initial Setup ¶

The package Company provides a minor mode company-mode.

To activate the company-mode, execute the command M-x company-mode that toggles the mode on and off. When it is switched on, the mode line (see (emacs)Mode line) should indicate its presence with an indicator ‘company’.

After company-mode had been enabled, the package auto-starts suggesting completion candidates. The candidates are retrieved and shown according to the typed characters and the default (until the user specifies otherwise) configurations.

To have Company always enabled for the following sessions, add the line (global-company-mode) to the Emacs configuration file (see (emacs)Init File).

Usage Basics ¶

By default — having company-mode enabled (see Initial Setup) — a tooltip with completion candidates is shown when the user types a few characters.

To initiate completion manually, use the command M-x company-complete.

To select next or previous of the shown completion candidates, use respectively key bindings C-n and C-p, then do one of the following:

• Hit RET to choose a selected candidate for completion.
• Hit TAB to expand the common part of all completions. Exactly what that means, can vary by backend. In the simplest case it’s the longest string that all completion start with, but when a backend returns non-prefix matches, it can implement the same kind of expansion logic for the input string.
• Hit C-g to stop activity of Company.

Commands ¶

Under the hood, mentioned in the previous section keys are bound to the commands of the out-of-the-box Company.

C-n ¶

M-n

Select the next candidate (company-select-next-or-abort, company-select-next).

C-p ¶

M-p

Select the previous candidate (company-select-previous-or-abort, company-select-previous).

RET ¶

<return>

Insert the selected candidate (company-complete-selection).

TAB ¶

<tab>

Insert the common part of all completion candidates (company-complete-common).

C-g ¶

<ESC ESC ESC>

Cancel company-mode activity (company-abort).

C-h ¶

<F1>

Display a buffer with the documentation for the selected candidate (company-show-doc-buffer). With a prefix argument (C-u C-h, C-u F1), this command toggles between temporary showing the documentation and keeping the documentation buffer up-to-date whenever the selection changes.

C-w ¶

Display a buffer with the definition of the selected candidate (company-show-location).

The full list of the default key bindings is stored in the variables company-active-map and company-search-map ¹.

Moreover, Company is bundled with a number of convenience commands that do not have default key bindings defined. The following examples illustrate how to assign key bindings to such commands.

(global-set-key (kbd "<tab>") #'company-indent-or-complete-common)

(with-eval-after-load 'company
  (define-key company-active-map (kbd "M-/") #'company-complete))

(with-eval-after-load 'company
  (define-key company-active-map
              (kbd "TAB")
              #'company-complete-common-or-cycle)
  (define-key company-active-map
              (kbd "<backtab>")
              (lambda ()
                (interactive)
                (company-complete-common-or-cycle -1))))

In the same manner, an additional key can be assigned to a command or a command can be unbound from a key. For instance:

(with-eval-after-load 'company
  (define-key company-active-map (kbd "M-.") #'company-show-location)
  (define-key company-active-map (kbd "RET") nil))