repository·master·Indexed 25 days ago
https://github.com/rrethy/vim-illuminateA plugin for Neovim and Vim that automatically highlights other occurrences of the word under the cursor using LSP, Tree-sitter, or regex matching. It provides navigation keymaps, text-objects for references, and a Lua API for configuration and state control.
To use vim-illuminate in Neovim, simply install the plugin. It works out of the box without any configuration.
By default, it provides the following keymaps and textobjects:
<a-n>: Move to the next reference.<a-p>: Move to the previous reference.<a-i>: Textobject for the reference currently illuminated under the cursor.For legacy Vim users, configuration is handled via global variables:
g:Illuminate_delay: Delay in milliseconds (default 0).g:Illuminate_highlightUnderCursor: Set to 0 to prevent highlighting the word under the cursor (default 1).g:Illuminate_ftHighlightGroups: A dictionary mapping filetypes to lists of syntax highlight groups to illuminate. Use the :blacklist suffix for a specific filetype to exclude certain groups.g:Illuminate_ftblacklist: A list of filetypes to disable illumination for.g:Illuminate_ftwhitelist: A list of filetypes to enable illumination for.To change the highlight group used for matches, link illuminatedWord to another group (e.g., CursorLine) within an autocmd.
Use require('illuminate').configure(config) to customize the plugin behavior.
Key configuration options include:
providers: An ordered list of providers used to find references (e.g., 'lsp', 'treesitter', 'regex').delay: Delay in milliseconds before highlighting starts.filetypes_denylist: Filetypes to exclude from illumination.filetypes_allowlist: Filetypes to include (requires setting filetypes_denylist = {} to override defaults).under_cursor: Boolean determining if the word under the cursor should be highlighted.large_file_cutoff: Line count threshold above which large_file_overrides are applied.min_count_to_highlight: Minimum number of matches required to trigger highlighting.should_enable: A callback function function(bufnr) return boolean end to dynamically enable/disable illumination.require('illuminate').configure({
providers = {
'lsp',
'treesitter',
'regex',
},
delay = 100,
filetypes_denylist = {
'dirbuf',
'dirvish',
'fugitive',
},
filetypes_allowlist = {},
under_cursor = true,
large_file_cutoff = 10000,
large_file_overrides = nil,
min_count_to_highlight = 1,
should_enable = function(bufnr) return true end,
case_insensitive_regex = false,
disable_keymaps = false,
})The following functions are available via require('illuminate'):
Configuration & State:
.configure(config): Override default settings..pause(), .resume(), .toggle(): Global state control..pause_buf(), .resume_buf(), .toggle_buf(): Buffer-local state control..freeze_buf(): Freeze highlights on the buffer (does not clear them)..unfreeze_buf(): Unfreeze the buffer..toggle_freeze_buf(): Toggle frozen state..invisible_buf(): Turn off highlighting for the buffer (engine still runs, allowing <c-n>/<c-p> navigation)..visible_buf(): Turn on highlighting for the buffer..toggle_visibility_buf(): Toggle visibility of highlights.Navigation & Selection:
.goto_next_reference(wrap): Move to the next reference. wrap defaults to 'wrapscan'..goto_prev_reference(wrap): Move to the previous reference. wrap defaults to 'wrapscan'..textobj_select(): Selects the current reference for use as a text-object.You can customize the visual appearance of illuminated words by defining these highlight groups:
IlluminatedWordText: Default group for references when no kind information is available.IlluminatedWordRead: Group for references of kind 'read'.IlluminatedWordWrite: Group for references of kind 'write'.hi def IlluminatedWordText gui=underline cterm=underline
hi def IlluminatedWordRead gui=underline cterm=underline
hi def IlluminatedWordWrite gui=underline cterm=underlineUse these commands to manage the illumination state globally or per buffer:
Global Commands:
:IlluminatePause: Pause all illumination.:IlluminateResume: Resume all illumination.:IlluminateToggle: Toggle between pause and resume.Buffer-local Commands:
:IlluminatePauseBuf: Pause illumination for the current buffer.:IlluminateResumeBuf: Resume illumination for the current buffer.:IlluminateToggleBuf: Toggle pause/resume for the current buffer.