local-highlight.nvim

Using regexes and extmarks to highlight uses of word under the cursor. Keeps updates local to currently visible lines, thus enabling blazingly fast performance.

In Action

Performance

This plugin replaces nvim-treesitter/nvim-treesitter-refactor highlight-definitions which performs poorly on large files.

install

Using Lazy:

  {
      'tzachar/local-highlight.nvim',
      config = function()
        require('local-highlight').setup()
      end
  },

Make sure to specify file types to attach to, or use the attach interface documented below.

Why Another Highlight Plugin?

Multiple plugins to highlight the word under the cursor exist. However, none of them solved all of the following issues for me:

1. Performance (especially on large files)
2. Highlight mechanics: by using extmarks, the current format of each highlighted word remains the same (e.g., italics, treesitter highlights)

Setup

You can setup local-highlight as follows:

require('local-highlight').setup({
    file_types = {'python', 'cpp'}, -- If this is given only attach to this
    -- OR attach to every filetype except:
    disable_file_types = {'tex'},
    hlgroup = 'Search',
    cw_hlgroup = nil,
    -- Whether to display highlights in INSERT mode or not
    insert_mode = false,
    min_match_len = 1,
    max_match_len = math.huge,
    highlight_single_match = true,
})

hlgroup

Specify the highlighting group to use.

By default, local-highlight will use the LocalHighlight highlight group, which it defines upon startup. If the group is already defined elsewhere in your config then it will not be overwritten. You can also use any other group you desire, e.g., see above where Search is used.

cw_hlgroup

Specify the highlighting group to use for the word under the cursor. Defaults to nil, which means "Do not apply any highlighting".

file_types and disable_file_types

The plugin works out of the box if you want to use FileTypes to attach to buffers.

To control this behavior, you have the option of setting the following options: file_types: nil by default, meaning attach to all file types. If set to a table, should contain file types relevant to the FileType autocommand, and will instruct the plugin to attach only to the specified fule types. disable_file_types: nil by default, meaning no exceptions when attaching to buffers. If set to a table, each fie type specified in the table will be skipped when attaching to buffers.

If you set file_types to an empty table, {}, local-highlight will not attach to any buffer on its own, and will leave all attach logic to the user.

insert_mode

If set to true, will also work during insert mode.

min_match_len and max_match_len

Set lower and upper limits on the length of the word being matched.

highlight_single_match

Set to false to stop highlighting words that only appear once.

API

If you want to directly attach the plugin to your buffers, you can use any autocommand to attach an event to your liking. For example, to attach to any buffer:

vim.api.nvim_create_autocmd('BufRead', {
  pattern = {'*.*'},
  callback = function(data)
    require('local-highlight').attach(data.buf)
  end
})

The plugin will take care not to reattach and to delete the autocommands when the buffer is closed.

Callbacks

Match Count

You can request the current count of matches. This can be used, e.g., in a status line plugin:

require('local-highlight').match_count(bufnr)

where bufnr is the buffer number the count is requested for or 0 for the current buffer.

User Commands

LocalHighlightToggle

Toggle local highlighting for the current buffer.

LocalHighlightOff

Turn local highlighting off for the current buffer.

LocalHighlightOn

Turn local highlighting on for the current buffer.

LocalHighlightStats

Echo timing information: total number of invocations and the average running time in milliseconds.

How the Plugin Works

local-highlight will attach to a buffer and register an autocommand for the CursorHold event. Once the event fires, local-highlight will grab the word under the cursor and will highlight all of the usages of the same word in the visible lines of the buffer.

One implication of using CursorHold is that interactivity depends on updatetime, which is 4000 by default. A good advice is to set it to something more reasonable, like 500, to get good interactivity.