The Basics

As with any exploration into Vim, we need to start from the ground floor — :help statusline .

When nonempty, this option determines the content of the statusline. The option consists of printf style ‘%’ items interspersed with normal text. Each statusline item is of the form:

%-0{minwid}.{maxwid}{item}

All fields except the {item} are optional. A single percent sign can be given as “%%”. Up to 80 items can be specified.

This may seem equal parts confusing and non-intuitive, but fear not…it’s not that bad.

The first thing is to tell Vim we want to see the statusline. You can do this by putting the following code in your .vimrc (vim) or init.vim (neovim).

set laststatus=2

Now that we have told Vim we are interested, we need to give it something to display! For a very basic example, type the following below:

set statusline=lightsaber!

When you reload Vim you should see:

Clearly, this statusline isn’t incredibly useful, but baby steps!

Syntax

Within the galaxy of statuslines, a special syntax exists. Every line is derived from individual items, with each corresponding to a particular piece of information. For instance, %f will give the relative path to the file currently present in the buffer.

echo "Hello, this is a .jedi file" >> lightsaber.jedi

Insert the following into your Vim config.

set statusline=%f

Open the file we created earlier. You should see your statusline with the name of the file printed on it.

This is, by and large, the formula for statuslines. You’ll be using these predefined mappings to create your weapon. There is one thing to note: how to combine multiple items.

The full list of mapings:

A minimal example that displays the file name, current line, total lines, and buffer number:

Formatting

We’re starting to get somewhere, a padawan no more. However, there are a few more tips, which are largely formatting quirks, to cover.

The first of these deals with controlling which side our items reside on. Specifically, the = symbol. An = denotes a separation point between sections.

Another formatting must-have is spacing. Spaces are escaped using backslashes — \ . The following example has one other symbol of note - < . The < is used to tell Vim where to truncate the line if it is too long.

With the knowledge you now posess you should be able to throw together something half-decent. But the journey is not over yet!

Expressions

There may come a time when you’re interested in including something that isn’t previously defined. This is where expressions will come into play. Within Vim’s statusline syntax anything between %{...} is evaluated as an expression, and substituted with the result. So, let’s say you’re too cool for set showmode and want it directly on your line, this is how you would achieve such a task.

This is your first step towards the darkside. You can now add just about anything your heart desires to your line. For instance, if you’re a crypto-nut, you could add the prices of Bitcoin and ETH — the possibilities are endless. For a great introduction to Vim Script head here. I’ve also included a few more examples below.

File Size

Read Only File

It is also worth noting that you can utilize Vim’s internal functions within expressions.

Color

The time has come. Which side will you pick? The life of a gritty minimalist accepting what the Vim gods have to offer. Or, will you indulge in the lush ecstasy of the rainbow? Personally, I could care less…but, luckily, the choice is yours!

There are two ways to go about adding color to your statusline. One is by piggy backing off of your colorscheme. The other is by defining the colors yourself.

Highlight Groups