🔎 visual-whitespace.nvim

Display white space characters in visual mode, like VSCode's renderWhitespace: selection.

_{GIF: Highlighting white spaces in linewise, blockwise, and charwise visual modes.}

In VSCode, the renderWhitespace options allows the user to choose how to display white space characters inside of the editor. Setting this option to selection allows the user to see only whitespace that is under the current selection. This is currently VSCode's default setting.

Features

_{GIF: Capturing tabs, non-breaking spaces, spaces, and line feed characters.}

visual-whitespace captures leading, middle, and trailing spaces; tabs; non-breaking spaces; and fileformat-specific new lines

Installation and Configuration

vim.pack, with lazy loading and using the setup() function

vim.pack.add({
  "https://github.com/mcauley-penney/visual-whitespace.nvim",
}, { load = false })

-- configuring with lazy load on entering visual mode
 vim.api.nvim_create_autocmd("ModeChanged", {
  pattern = "*:[vV\22]",
  once = true,
  callback = function()
    vim.cmd.packadd("visual-whitespace.nvim")
    require("visual-whitespace").setup({
      -- your opts here ...
    })
  end,
})

lazy.nvim

  {
    'mcauley-penney/visual-whitespace.nvim',
    event = "ModeChanged *:[vV\22]", -- optionally, lazy load on entering visual mode
    opts = {
      -- your opts here ...
    }
  }

Options and defaults

{
  enabled = true,
  highlight = { link = "Visual", default = true },
  match_types = {
    space = true,
    tab = true,
    nbsp = true,
    lead = false,
    trail = false,
  },
  list_chars = {
    space = "·",
    tab = "↦",
    nbsp = "␣",
    lead = "‹",
    trail = "›",
  },
  fileformat_chars = {
    unix = "↲",
    mac = "←",
    dos = "↙",
  },
  ignore = { filetypes = {}, buftypes = {} },
}

Highlighting

visual-whitespace defines the VisualNonText highlight group. You can set this via the plugin configuration or through Neovim's Lua API, which allows for color schemes to support visual-whitespace:

-- This can go in your color scheme or in your plugin config
vim.api.nvim_set_hl(0, "VisualNonText", { fg = "#5D5F71", bg = "#24282d"})

The plugin's highlighting order has a precedence: default → color scheme → user configuration.

Functions

visual-whitespace affords the following user-facing functions:

Lua	Description
require("visual-whitespace").toggle()	enable or disable visual-whitespace.nvim

Use them in keymaps like:

init = function()
    vim.keymap.set({ 'n', 'v' }, "<leader>tw", require("visual-whitespace").toggle, {})
end

Versions and support

Branch	Neovim Version Compatibility	Modes Supported	Characters Supported	Speed
main	>=0.12	Charwise, linewise, blockwise	Spaces, leading spaces, trailing spaces, tabs, fileformat-specific newlines	Redraw-time, viewport-specific
compat-v10	<0.11	Charwise, linewise	Spaces, tabs, linefeeds (Unix newlines)	Slow

• main is the primary development branch. The documentation above is for this branch.
• compat-v10 will accept PRs as long as they are compatible with Neovim < 0.11, but the maintainer will not develop this branch.