One of the things that took me awhile to figure out when I started using Vim was how to display whitespace characters. Whitespace characters are characters that take up space in a document but are not visible to the user. Examples include spaces, tabs, and new-lines characters.
In this post, I’m going to explain how to configure Vim to display whitespace characters. I’ll also touch on problems you may run into and how to avoid them.
Turning On Whitespace Characters
Vim refers to the mode that is used to display whitespace characters as list mode. By default, it’s turned off. To turn it on you can enter set list on the Vim command line or add it to your vimrc file. To turn it off again, you can use the
set nolist command.
Setting Which Whitespace Characters Are Displayed
List mode is configured to only show the end-of-line characters ($) by default. If you want to show more characters or configure how the characters are displayed you can set the
listchars is a global variable whose value can be set to a comma-separated list of key/value pairs. The key represents the whitespace character and the value represents how it will be displayed. For example, the default value for
eol:$. This means that when list mode is on end-of-line characters will show up as $.
Options that you can use with
listchars are below. They were taken from the Vim help documentation.
eol - Character to show at the end of each line.
tab - Two characters to be used to show a tab.
trail - Character to show for trailing spaces.
extends - Character to show in the last column when the line continues beyond the right of the screen.
precedes - Character to show in the first column when the line continues beyond the left of the screen.
conceal - Character to show in place of concealed text, when conceallevel is set to 1.
nbsp - Character to show for a space.
Here is how I’ve set
listchars in my configuration:
It’s Not Working!
If you’ve turned on list mode and can’t see whitespace characters, the issue may be with your colorscheme. List mode uses the
SpecialKey highlighting groups to determine what color the whitespace characters will be when displayed. In some cases, these highlighting groups may be set to the same color as your background. In short, if the background is black and whitespace characters are black, you won’t see them! Check your colorscheme and make sure these groups are set to a distinct color.
The Vim help documentation is an excellent resource if you know how to find what you’re looking for. You can find more information about
list and a
listchars by entering
help list or
help listchars on the Vim command line.