mini.cursorword documentation

Generated from the main branch of ‘mini.nvim’

mini.cursorword Autohighlight word under cursor

Module

Features:

Autohighlight word under cursor with customizable delay.
Current word under cursor can be highlighted differently.
Highlighting is triggered only if current cursor character is a [:keyword:].
Highlighting stops in insert and terminal modes.
“Word under cursor” is meant as in Vim’s <cword>: something user would get as ‘iw’ text object.

Setup

This module needs a setup with require('mini.cursorword').setup({}) (replace {} with your config table). It will create global Lua table MiniCursorword which you can use for scripting or manually (with :lua MiniCursorword.*).

See MiniCursorword.config for config structure and default values.

You can override runtime config settings locally to buffer inside vim.b.minicursorword_config which should have same structure as MiniCursorword.config. See mini.nvim-buffer-local-config for more details.

Highlight groups

MiniCursorword - highlight group of a non-current cursor word. Default: plain underline.
MiniCursorwordCurrent - highlight group of a current word under cursor. Default: links to MiniCursorword (so :hi clear MiniCursorwordCurrent will lead to showing MiniCursorword highlight group). Note: To not highlight it, use the following Lua code:
```
vim.api.nvim_set_hl(0, 'MiniCursorwordCurrent', {})
```

To change any highlight group, set it directly with nvim_set_hl().

Disabling

To disable core functionality, set vim.g.minicursorword_disable (globally) or vim.b.minicursorword_disable (for a buffer) to true. Considering high number of different scenarios and customization intentions, writing exact rules for disabling module’s functionality is left to user. See mini.nvim-disabling-recipes for common recipes. Note: after disabling there might be highlighting left; it will be removed after next highlighting update.

Module-specific disabling:

Don’t show highlighting if cursor is on the word that is in a blocklist of current filetype. In this example, blocklist for “lua” is “local” and “require” words, for “javascript” - “import”:

_G.cursorword_blocklist = function()
  local curword = vim.fn.expand('<cword>')
  local filetype = vim.bo.filetype

  -- Add any disabling global or filetype-specific logic here
  local blocklist = {}
  if filetype == 'lua' then
    blocklist = { 'local', 'require' }
  elseif filetype == 'javascript' then
    blocklist = { 'import' }
  end

  vim.b.minicursorword_disable = vim.tbl_contains(blocklist, curword)
end

-- Make sure to add this autocommand *before* calling module's `setup()`.
vim.cmd('au CursorMoved * lua _G.cursorword_blocklist()')

setup()

MiniCursorword.setup({config})

Module setup

Parameters

{config} (table|nil) Module config table. See MiniCursorword.config.

Usage

require('mini.cursorword').setup() -- use default config
-- OR
require('mini.cursorword').setup({}) -- replace {} with your config table

config

MiniCursorword.config

Defaults

MiniCursorword.config = {
  -- Delay (in ms) between when cursor moved and when highlighting appeared
  delay = 100,
}