Next: , Previous: , Up: Company   [Contents]


Customization

Emacs provides two equally acceptable ways for user preferences configuration: via customization interface (for more details, see (emacs)Easy Customization) and a configuration file (see (emacs)Init File). Naturally, Company can be configured by both of these approaches.


Customization Interface

In order to employ the customization interface, run M-x customize-group RET company.

This interface outputs all the options available for user customization, so you may find it beneficial to review this list even if you are going to configure Company with the configuration file.

For instructions on how to change the settings, see (emacs)Changing a Variable.


Configuration File

Company is a customization-rich package. This section lists some of the core settings that influence the overall behavior of the company-mode.

User Option: company-minimum-prefix-length

This is one of the values (together with company-idle-delay), based on which Company auto-stars looking up completion candidates. This option configures how many characters have to be typed in by a user before candidates start to be collected and displayed. An often choice nowadays is to configure this option to a lower number than the default value of 3.

User Option: company-idle-delay

This is the second of the options that configure Company’s auto-start behavior (together with company-minimum-prefix-length). The value of this option defines how fast Company is going to react to the typed input, such that setting company-idle-delay to 0 makes Company react immediately, nil disables auto-starting, and a larger value postpones completion auto-start for that number of seconds. For an even fancier setup, set this option value to a predicate function, as shown in the following example:

(setq company-idle-delay
      (lambda () (if (company-in-string-or-comment) nil 0.3)))
User Option: company-global-modes

This option allows to specify in which major modes company-mode can be enabled by (global-company-mode). See Initial Setup. The default value of t enables Company in all major modes. Setting company-global-modes to nil equal in action to toggling off global-company-mode. Providing a list of major modes results in having company-mode enabled in the listed modes only. For the opposite result, provide a list of major modes with not being the first element of the list, as shown in the following example:

(setq company-global-modes '(not erc-mode message-mode eshell-mode))
User Option: company-selection-wrap-around

Enable this option to loop (cycle) the candidates’ selection: after selecting the last candidate on the list, a command to select the next candidate does so with the first candidate. By default, this option is disabled, which means the selection of the next candidate stops on the last item. The selection of the previous candidate is influenced by this option similarly.

User Option: company-require-match

To allow typing in characters that don’t match the candidates, set the value of this option to nil. For an opposite behavior (that is, to disallow non-matching input), set it to t. By default, Company is configured to require a matching input only if a user manually enables completion or selects a candidate; by having the option configured to call the function company-explicit-action-p.

User Option: company-lighter-base

This user options allows to configure a string indicator of the enabled company-mode in the mode line. The default value is ‘company’.

User Option: company-insertion-on-trigger

One more pair of the user options may instruct Company to complete with the selected candidate by typing one of the company-insertion-triggers. The user option company-insertion-on-trigger can be enabled or disabled by setting its value to one of: nil, t, or a predicate function name. See (eintr)Predicate.

User Option: company-insertion-triggers

This option has an effect only when company-insertion-on-trigger is enabled. The value can be one of: a string of characters, a list of syntax description characters (see (elisp)Syntax Class Table), or a predicate function. By default, this user option is set to the list of the syntax characters: (?\ ?\) ?.), which translates to the whitespaces, close parenthesis, and punctuation. It is safe to configure the value to a character that can potentially be part of a valid completion; in this case, Company does not treat such characters as triggers.

Hooks

Company exposes the following life-cycle hooks:

User Option: company-completion-started-hook
User Option: company-completion-cancelled-hook
User Option: company-completion-finished-hook
User Option: company-after-completion-hook

Next: , Previous: , Up: Company   [Contents]