Key Features • Requirements • Installation • Configuration • Commands • Add-on

Words are sourced asynchronously from various sources:

• Buffers
• Dictionary files
• Code completion sourced from LSP client
• Snippets from vim-vsnip client
• Words and bigrams from Ngrams database
• Vim's omnifunc
• Path search
• Vim's abbreviations
• Vim9script language (similar to LSP)
• Tmux panes
• Tag names

All crucial source modules are integrated, eliminating the need to manage multiple plugins. Users have the flexibility to enable or disable each completion source and customize settings on a per-file-type basis (:h filetype).

Completion items are sorted according to the following criteria:

• Recency (using a LRU cache)
• Length of item
• Priority
• Proximity of item (for buffer completion)
• Case match

• Vim version 9.0 or higher

Install it via vim-plug.

vim9script
plug#begin()
Plug 'girishji/vimcomplete'
plug#end()

call plug#begin()
Plug 'girishji/vimcomplete'
call plug#end()

Install using Vim's built-in package manager.

$ mkdir -p $HOME/.vim/pack/downloads/opt
$ cd $HOME/.vim/pack/downloads/opt
$ git clone https://github.com/girishji/vimcomplete.git

packadd vimcomplete

The completion sources mentioned above, aside from buffer, path, and lsp completion, are not enabled by default. This section provides instructions on configuring both the completion sources and the completion engine itself.

This entity retrieves completion items from the enabled completion sources and then displays the popup menu.

The current buffer, as well as other open buffers, are searched for completion candidates using an asynchronous mechanism with a timeout. This approach ensures that the completion engine is not slowed down by large buffers.

The dictionary provider is capable of searching an arbitrary list of words placed one per line in a text file. These words can encompass any non-space characters, and the file doesn't necessarily need to be sorted. This feature presents various opportunities. For instance, you can create a dictionary akin to Pydiction, enabling the completion of keywords, functions, and method names for any programming language. Moreover, it can efficiently search a sorted dictionary using binary search.

Unsorted dictionaries are searched in linear time O(n), but they tend to perform acceptably well for file sizes below 3MB (performance might vary depending on your system). Only one unsorted dictionary is used for completion, while any number of sorted dictionaries can be used simultaneously.

Additionally, the dictionary files can include comments.

Further information about setting up configurations will be available later. Nonetheless, here is a sample configuration specifically targeting the dictionary source. Dictionary files can be configured individually for each 'filetype' (:h filetype).

vim9script
var dictproperties = {
    python: { sortedDict: false },
    text: { sortedDict: true }
}
var vcoptions = {
    dictionary: { enable: true, priority: 11, filetypes: ['python', 'text'], properties: dictproperties },
}
autocmd VimEnter * g:VimCompleteOptionsSet(vcoptions)
autocmd FileType text set dictionary =/usr/share/dict/words

By adding the following snippet to your vimrc, you can add custom completions for each filetype, say python, by adding a text file dicts/python into the vimrc folder:

vim9script
g:vimfiles_dir = &runtimepath->split(',')[0]
autocmd FileType * {
    var dict = $'{g:vimfiles_dir}/dicts/{expand("<amatch>")}'->resolve()->fnamemodify(':p')
    if dict->filereadable()
        exe $'setlocal dictionary={dict}'
    endif
}

autocmd VimEnter * call g:VimCompleteOptionsSet(vcoptions)

This source obtains autocompletion items from the LSP client.

This source provides snippet completion from vim-vsnip.

This source is kept as a separate plugin since it includes large database files. Please see ngram-complete for installation and usage instructions.

This source completes items emitted by the function set in omnifunc (:h 'omnifunc').

Vim provides language based autocompletion through Omni completion for many languages (see $VIMRUNTIME/autoload). This is a lightweight alternative to using LSP.

Vim sets the omnifunc option automatically when file type is detected.

Also, any user defined omnifunc can also be used for autocompletion.

Both relative and absolute path names are completed.

Abbreviations (:h abbreviations) are completed based on the id.

This source completes Vim9 script function names, arguments, variables, reserved words and the like. Enable this if you are developing a Vim plugin or configuring a non-trivial .vimrc.

Words are sourced asynchronously from adjacent tmux panes, ensuring Vim won't hang even with a lot of output in the tmux windows.

Tag names are autocompleted if tags file is available.

Options can be configured using the global function g:VimCompleteOptionsSet(). The example below illustrates how to enable and configure completion sources. Please note that not all options are demonstrated here; for a comprehensive list of all available options, refer to the tables provided above.

vim9script
var options = {
    completor: { shuffleEqualPriority: true, postfixHighlight: true },
    buffer: { enable: true, priority: 10, urlComplete: true, envComplete: true },
    abbrev: { enable: true, priority: 10 },
    lsp: { enable: true, priority: 10, maxCount: 5 },
    omnifunc: { enable: false, priority: 8, filetypes: ['python', 'javascript'] },
    vsnip: { enable: true, priority: 11 },
    vimscript: { enable: true, priority: 11 },
    ngram: {
        enable: true,
        priority: 10,
        bigram: false,
        filetypes: ['text', 'help', 'markdown'],
        filetypesComments: ['c', 'cpp', 'python', 'java'],
    },
}
autocmd VimEnter * g:VimCompleteOptionsSet(options)

autocmd VimEnter * call g:VimCompleteOptionsSet(options)

You can map the <Tab> and <S-Tab> keys to navigate autocomplete items in insert mode. By default, Vim uses CTRL-N and CTRL-P to cycle through completion menu options. <Tab> and <S-Tab> also jump between snippet placeholders where appropriate.

To enable <Tab> and <S-Tab> for this purpose, add the following to your configuration:

vim9script
let g:vimcomplete_tab_enable = 1

Note: Enabling this option will remove any existing mappings for <Tab> and <S-Tab>.

If you'd like to retain <Tab> and <S-Tab> mappings from other plugins, unset the above variable and instead use these custom mappings, substituting {rhs} as needed (using "\<Tab>" as "{rhs}" will behave the same as setting the variable):

inoremap <buffer><expr> <tab>   g:VimCompleteTab() ?? "{rhs}"
inoremap <buffer><expr> <s-tab> g:VimCompleteSTab() ?? "{rhs}"

This configuration allows <Tab> and <S-Tab> to integrate with other plugin mappings.

Alternatively, you can use the keys <Plug>(vimcomplete-tab) and <Plug>(vimcomplete-s-tab) directly in your custom mappings.

<Enter> is mapped by default to insert the currently selected item and/or insert a literal <CR>, depending on configuration (see noNewlineInCompletion and noNewlineInCompletionEver options).

In case of conflicts with other plugins, this mapping can be disabled entirely:

vim9script
g:vimcomplete_cr_enable = 0

In this case, the user must define an appropriate <CR> mapping to resolve conflicts between plugins. When creating your mapping, if alwaysOn is enabled, consider emitting <Plug>(vimcomplete-skip) to prevent the next keystroke from automatically reactivating the completion popup.

You can use Pmenu, PmenuThumb, PmenuSbar, PmenuSel, PmenuKind, PmenuKindSel, PmenuExtra and PmenuExtraSel Vim highlight groups to alter the appearance of the popup menu.

You can also customize the appearance of the column containing the 'kind' attribute in the menu. For example, to modify the appearance of the 'Keyword' kind, configure the PmenuKindKeyword highlight group. Refer to the list for all available 'kind' items.

If postfixHighlight option is enabled, you can utilize the VimCompletePostfix highlight group to adjust the appearance of text adjacent to the completion. By default, it is linked to DiffChange.

Vim's completion system can display an additional popup window (referred to as the "info" window) next to the selected menu item when supplementary information is available.

To apply basic customizations, you can use the completepopup option. For example:

autocmd VimEnter * set completepopup =border:off,highlight:Normal

This provides limited customization. For advanced control over the appearance and behavior of the "info" window, use the g:VimCompleteInfoWindowOptionsSet() function. This function accepts a dictionary of popup window options. Refer to :h popup_create-arguments for detailed descriptions. Here’s an example:

g:VimCompleteInfoWindowOptionsSet({
    drag: false,    # Disable dragging
    close: 'none',  # Disable close button
    resize: false,  # Disable resizing
})

Info window can be scrolled using the following keys: <Plug>(vimcomplete-info-window-pageup), <Plug>(vimcomplete-info-window-pagedown), <Plug>(vimcomplete-info-window-home), and <Plug>(vimcomplete-info-window-end). Here's an example mapping:

inoremap <C-b> <Plug>(vimcomplete-info-window-pageup)
inoremap <C-f> <Plug>(vimcomplete-info-window-pagedown)

Commands are available to list completion sources and to enable or disable the plugin.

The following command displays a list of completion sources enabled for the current buffer.

:VimCompleteCompletors

Autocompletion is enabled by default. At any time, you can enable or disable the plugin using the following commands:

:VimCompleteEnable
:VimCompleteDisable

You can selectively enable autocompletion for specific file types. For instance, enable autocompletion for c, cpp, python, vim, text, and markdown files.

:VimCompleteEnable c cpp python vim text markdown

To start Vim with autocompletion disabled, set the following variable.

g:vimcomplete_enable_by_default = false

VimCompleteEnable takes a space-separated list of file types as an argument. If no argument is specified, autocompletion is enabled for all file types.

When Vim is started without any arguments or a new buffer is created with :bufnew, it opens an unnamed buffer. This buffer is not associated with any file type. To enable/disable autocompletion on this buffer use the following variable. It is set by default.

g:vimcomplete_noname_buf_enable = true

Each item returned by the LSP server has a type associated with it, which can be displayed on the popup menu. To customize , you need to use the option customCompletionKinds and set all custom kinds in the completionKinds. The following table has all default LSP kinds:

For example, if you want to change the "Method" kind to the kind "method()":

vim9script
g:VimCompleteOptionsSet({ Completor: {
    customCompletionKinds: true,
    completionKinds: {
        "Method": "method()"
    }
})

In the completion popup, will show something like this: >

    var file = new File()

    file.cre
        | create                method() |
        | createIfNotExists     method() |
        | ...                            |

Start by examining the implementation of an external plugin like ngrams-viewer (which spawns a new process to handle http requests) or ngram-complete.

The completion engine employs an interface similar to Vim's complete-functions. However, the function is invoked in three ways instead of two:

• First, to find the start of the text to be completed.
• Next, to check if completion candidates are available.
• Lastly, to find the actual matches.

The first and last invocation are identical to Vim's complete-functions. During the second invocation, the arguments are:

• findstart: 2
• base: empty

The function must return true or false to indicate whether completion candidates are ready. Only when this return value is true will the function be invoked for the third time to get the actual matches. This step is essential for asynchronous completion.

The name of the completion function does not matter, but it should take two arguments: findstart: Number and base: String, and return <any>. Register this function with the completion engine by calling vimcompletor.Register(). Use the User event of type VimCompleteLoaded to time the registration.

When users set options through the configuration file, a User event with type VimCompleteOptionsChanged is issued. The plugin should register for this event and update its internal state accordingly.

1. Devdocs.vim - browse documentation from devdocs.io.

2. Scope.vim - fuzzy find anything.

3. VimBits - curated suite of lightweight Vim plugins.

4. VimSuggest - autocompletion for Vim's command-line.

Pull requests are welcomed.

• asyncomplete
• nvim-cmp