🔎 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:

• spaces
• tabs
• non-breaking spaces
• leading and trailing spaces
  • overrides the general spaces, like the default behavior of :h listchars
• fileformat-specific new lines
  • Note: VSCode does not currently have support for any new line character display. This plugins enhances Vim's and Neovim's existing new line character support by displaying new lines that are specific to the current fileformat.

Installation

To install the plugin with the default settings using Lazy:

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

Configuration

Method

You can configure visual-whitespace using either:

1. your plugin manager (e.g. lazy.nvim), or

opts = {
    -- your opts here ...
}

2. the vim.g.visual_whitespace global dictionary

 vim.g.visual_whitespace = {
     -- your opts here ...
 }

Options and defaults

opts = {
  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 → colors cheme → 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.11	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.