For some Vimmers, their statusline is like the Lightsaber of a Jedi. Each one similar, yet unique — the aesthetic cherry revealing a lurking identity. This notion has led to projects like Powerline, Airline, and Lightline. While all interesting, this tutorial is about doing it the old school way. We’ll be traveling to a metaphorical Dagobah to craft our statusline using the methods of the force — Vim script.
Before we get going, here is a preview of the syntax. The screenshot below is my current statusline, alongside the code used to generate it.
Code below
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
The first method for coloring borrows from your colorscheme. For example, #function# will utilize the defined highlighting for the function keyword. The next image is my statusline using this technique:
The accompanying code below
User1..9 Colors
The second method relies on colors that you’ll define. If you want a high degree of control, this is your choice. We’ll briefly dive back into Vim’s help to get an overview before preceeding.
Set highlight group to User{N}, where {N} is taken from the minwid field, e.g. %1. Restore normal highlight with % or %0*. The difference between User{N} and StatusLine will be applied to StatusLineNC for the statusline of non-current windows. The number N must be between 1 and 9. See |hl-User1..9|
That may be slightly confusing, so let’s hop into an example. The first thing to do is specify our colors of interest. The syntax is akin to creating a custom colorscheme.
hi User1 ctermbg=green ctermfg=red guibg=green guifg=redhi User2 ctermbg=red ctermfg=blue guibg=red guifg=bluehi User3 ctermbg=blue ctermfg=green guibg=blue guifg=green
In order to apply it, you designate the User number followed by a * - %1* User1 colors. Below is a full blown example.
The code for this line is below
A lightline-esque version:
Your options are only limited by your imagination and time.
Next Steps
Despite all that has been covered, there is still a lot to learn. I’ll briefly cover a few more topics before suggesting additional resources.
Special Characters
The ‹‹ ›› on my line are solely for aesthetics. You can go to unicode-table to find interesting characters.
Different Colors Per Mode
If you are determined to do this without using a plugin it is possible. The easiest path will be using augroupand Events. I’d start with a :help Events. Then you’ll set up an augroup for your user defined colors and switch them based off the event. I’m not going to give a solution because I’m guessing it’s the sort of thing that would incite some motivation. Thus, it would be a worthwhile task to start to learn some Vim script. It’s honestly not too bad. There are other ways, however at some point you end up re-inventing the wheel.