Skip to content
Switch branches/tags


Failed to load latest commit information.
Latest commit message
Commit time


Building on Vim’s spell-check and thesaurus/dictionary completion

Features of this plugin:

  • Specify the languages to be used in spell-check
  • Specify a list of thesauruses for synonym completion
  • Specify a list of dictionaries for word completion
  • Specify a list of spellfiles for custom word-check additions
  • Opt-in key mappings for Normal mode thesaurus and dictionary completion
  • Buffer-scoped configuration (leaves your global settings alone)

Though principally used as a editor for code, Vim flirts with those of us editing documentation and prose by providing spell-check as well as completion capabilities using both dictionary and thesaurus files.

While we can configure these settings in our .vimrc files, we often need more granular control, where defaults are leveraged and configuration is applied by file type to the current buffer. This plugin fills that gap.


Best Installed using Pathogen, Vundle, Neobundle, or your favorite Vim package manager.


Because spell-check, thesaurus, etc. isn’t needed for all file types, you can configure it per file type in your .vimrc:

set nocompatible
filetype plugin on       " may already be in your .vimrc

augroup lexical
  autocmd FileType markdown,mkd call lexical#init()
  autocmd FileType textile call lexical#init()
  autocmd FileType text call lexical#init({ 'spell': 0 })
augroup END

In the last autocmd statement above, dictionaries and thesauruses are configured for the text file type, but spell-check is disabled by default.

lexical enables spell-check by default for buffers in which it is initialized. You can change that default setting in your .vimrc:

let g:lexical#spell = 1         " 0=disabled, 1=enabled

Spell-check language configuration

Vim’s global spelllang (note three ls) may already specify a default language. You can query it with a simple command:

:echo &spelllang
=> ‘en

If desired, you can be more specific, overriding the global spelllang in your .vimrc:

let g:lexical#spelllang = ['en_us','en_ca',]

Available spell files can be found at Vim will attempt to download those which are not installed locally. For more detail see

:help spellfile.vim

Thesaurus configuration

If you don’t have one already, download a thesaurus, such as Grady Ward’s Moby Thesaurus at Zeke's moby thesaurus, or on Project Gutenberg and extract the mthesaur.txt file. By default lexical will look for it at the following path:

let g:lexical#thesaurus = ['~/.vim/thesaurus/mthesaur.txt',]

You can specify multiple paths to thesauruses in the list.

Dictionary configuration

On Unix-based systems (including OS X) the dictionary will default to:

let g:lexical#dictionary = ['/usr/share/dict/words',]

You can specify multiple paths to dictionaries in the list.

Spellfile configuration

On Unix-based systems (including OS X) the spellfile will default to:

let g:lexical#spellfile = ['~/.vim/spell/en.utf-8.add',]

You can specify a single path for spellfile in the list.


Vim offers many standard key mappings for spell-checking and completion.


These are the Normal mode commands:

  • ]s - Move to next misspelled word after the cursor.
  • [s - Like ]s but search backwards
  • ]S - Like ]s but only stop at bad words, not at rare words or words for another region.
  • [S - Like ]S but search backwards.

With the following key mappings you can use Visual mode selection to select the characters (including whitespace). Otherwise the word under the cursor is used.

  • zg - Mark as a good word

  • zw - Like zg but mark the word as a wrong (bad) word.

  • zug - Unmark as good word

  • zuw - Unmark as wrong (bad) word

  • z= - For the word under/after the cursor suggest correctly spelled words

  • 1z= - Use the first suggestion, without prompting

  • . - Redo - repeat last word replacement

  • :spellr - Repeat the replacement done by z= for all matches with the replaced word in the current window

For spelling suggestions while in Insert mode:

  • «CTRL-X» «CTRL-S» (or «CTRL-X» «s» for terminal users) - suggest spelling, using «CTRL-P» and «CTRL-N» to navigate.

For a convenient pop-up list of suggestions from Normal mode, you can map an available key of your choice in your .vimrc:

let g:lexical#spell_key = '<leader>s'

This buffer-scoped mapping is strictly opt-in. No key is mapped by default.

Thesaurus lookup

For thesaurus lookup while in Insert mode:

  • «CTRL-X» «CTRL-T» - thesaurus lookup, using «CTRL-P» and «CTRL-N» to navigate.

For convenient Normal mode thesaurus lookup from the cursor position, you can map an available key of your choice in your .vimrc:

let g:lexical#thesaurus_key = '<leader>t'

This buffer-scoped mapping is strictly opt-in. No key is mapped by default.

Dictionary completion

For dictionary completion while in Insert mode:

  • «CTRL-X» «CTRL-K» - dictionary completion, using «CTRL-P» and «CTRL-N» to navigate.

For convenient Normal mode dictionary lookup from the cursor position, you can map an available key of your choice in your .vimrc:

let g:lexical#dictionary_key = '<leader>k'

This buffer-scoped mapping is strictly opt-in. No key is mapped by default.

Define your own commands

Sometimes you need a highly-customized environment for spell-check and completion. You can define your own commands in your .vimrc to meet that need. For example:

command! -nargs=0 LexMed call lexical#init({
                    \ 'spell': 1,
                    \ 'spelllang':  ['en', 'medical'],
                    \ 'dictionary': ['~/.vim/dictionary/medical_terms.txt',
                    \                '/usr/share/dict/words',
                    \               ],
                    \ 'thesaurus':  ['~/.vim/dictionary/medical_synonyms.txt',
                    \                '~/.vim/thesaurus/mthesaur.txt',
                    \               ],
                    \ 'spellfile':  ['~/.vim/spell/en.add'],
                    \ })

Then to quickly configure Vim for the current buffer, enter the command:


Where you are providing an explicit value, it will use that. Where you do not, it will fall back to your specified defaults or global settings.

See also

The ervandew/supertab plugin will make these Insert mode completions available via the «tab» key.

If you find this plugin useful, you may want to check out these others by @reedes:

Future development

If you’ve spotted a problem or have an idea on improving this plugin, please post it to the github project issue page.