Roll your own Neovim statusline

Unknown — Sat, 18 Apr 2026 00:00:00 +0000

tl;dr</a></h2>
You can create a (really) nice statusline quite easily without dedicated plugins:

Neovim's default statusline</a></h2>
The unconfigured statusline looks something like this:

You get:

The path to the current file</li>
A modified status indicator (`[+]</code> if there are unsaved changes)</li>`
`LSP diagnostics (E:1 W:2</code>)</li>`
`The cursor position (42,0-1</code>)</li>`
`The position of the viewport (Bot</code>, i.e. bottom of the page)</li> </ul> For my money this is actually a great set of defaults. But if you also spend hours every day in this editor, you may ask yourself, does it spark joy? For me, an ideal, Marie Kondo-style statusline should be:`Fancy but understated</li> Lightweight</li> Hackable</li> </ul> This turns out to be very achievable with nvim's built-in functionality - here's how. What's in a statusline?</a></h2> The statusline help page</a> says this about the statusline option: Contains printf-style "%" items interspersed with normal text, where each item has the form: %-0{minwid}.{maxwid}{item}</code> </blockquote> It also lists a bunch of options you can use as the {item}</code>, although for us it's sufficient to note only three: Item</th> Meaning</th></tr></thead> %#Bla#</code></td> Apply the Bla</code> highlight group to anything that comes next</td></tr> %=</code></td> Anything before this will be to the left of the status bar; anything after will be to the right</td></tr> %{%</code></td> Anything after this is evaluated and then re-evaluated in the context of the statusline. This item is closed using %}</code>^{1</a>.</td></tr> </tbody></table> Creating a statusline using Lua</a></h2> First let's create a Lua function which returns a string formatted as per the above advice. I'm putting this in nvim/lua</code> and returning it at the end of the script - this way I can just require()</code> the file from anywhere in my Neovim config. -- nvim/lua/statusline.lua return { render = function() local active_win = vim.fn.win_getid() local status_win = tonumber(vim.g.actual_curwin) if status_win ~= active_win then return "Statusline for inactive windows" end return table.concat({ "Statusline left-aligned stuff", "%=", -- Left/right separator "Statusline right-aligned stuff", }) end, }</code></pre> We can then set our statusline to call render()</code> like so: -- nvim/init.lua vim.opt.statusline = "%{%v:lua.require'statusline'.render()%}"</code></pre> With this setup we can now easily insert arbitrary components into our statusline. You might notice that I also snuck in some special behaviour for lines in non-focussed windows - you don't have to keep this, but all the other kids are doing it. Our statusline now looks like this: Setting up some highlight groups</a></h2> For a truly fancy setup you will probably want to define some custom highlights. You can use preexisting ones, but IMO it's a little clearer to define some dedicated highlight groups. You can put this code at the top of nvim/lua/statusline.lua</code>: local hl = function(group) return vim.api.nvim_get_hl(0, { name = group, link = false, create = false, }) end local set_hl_groups = function() local base = hl("StatusLine") for group, opts in pairs({ ModeNormal = { fg = base.bg, bg = hl("StatusLine").fg }, ModePending = { fg = base.bg, bg = hl("Comment").fg }, ModeVisual = { fg = base.bg, bg = hl("SpecialKey").fg }, ModeInsert = { fg = base.bg, bg = hl("DiffAdded").fg }, ModeCommand = { fg = base.bg, bg = hl("Number").fg }, ModeReplace = { fg = base.bg, bg = hl("Constant").fg }, Bold = { fg = base.fg, bg = base.bg, bold = true }, Dim = { fg = hl("LineNr").fg, bg = base.bg }, }) do group = "StatusLine" .. group vim.api.nvim_set_hl(0, group, opts) opts.fg, opts.bg = opts.bg, opts.fg vim.api.nvim_set_hl(0, group .. "Inverted", opts) end end -- Compile and apply our custom highlights set_hl_groups() -- Re-compile statusline colours when the colorscheme changes vim.api.nvim_create_autocmd("ColorScheme", { group = vim.api.nvim_create_augroup("my_statusline", {}), desc = "Re-apply statusline highlights on colorscheme change", callback = set_hl_groups, })</code></pre> set_hl_groups()</code> creates a bunch of highlight groups like "StatusLineBold"</code>, "StatusLineBoldInverted"</code>, "StatusLineModeNormal"</code>, etc. These reuse attributes of existing highlight groups here - we could define our own colours, but these wouldn't look good with every colorscheme. Creating a component</a></h2> local mode_component = function() -- Note: termcodes \19 and \22 are ^S and ^V ---- stylua: ignore local mode_settings = { ["n"] = { name = "NORMAL", hl = "Normal" }, ["no"] = { name = "OP-PENDING", hl = "Pending" }, ["nov"] = { name = "OP-PENDING", hl = "Pending" }, ["noV"] = { name = "OP-PENDING", hl = "Pending" }, ["no\22"] = { name = "OP-PENDING", hl = "Pending" }, ["niI"] = { name = "NORMAL", hl = "Normal" }, ["niR"] = { name = "NORMAL", hl = "Normal" }, ["niV"] = { name = "NORMAL", hl = "Normal" }, ["nt"] = { name = "NORMAL", hl = "Normal" }, ["ntT"] = { name = "NORMAL", hl = "Normal" }, ["v"] = { name = "VISUAL", hl = "Visual" }, ["vs"] = { name = "VISUAL", hl = "Visual" }, ["V"] = { name = "V-LINE", hl = "Visual" }, ["Vs"] = { name = "V-LINE", hl = "Visual" }, ["\22"] = { name = "V-BLOCK", hl = "Visual" }, ["\22s"] = { name = "V-BLOCK", hl = "Visual" }, ["s"] = { name = "SELECT", hl = "Insert" }, ["S"] = { name = "S-LINE", hl = "Normal" }, ["\19"] = { name = "S-BLOCK", hl = "Normal" }, ["i"] = { name = "INSERT", hl = "Insert" }, ["ic"] = { name = "INSERT", hl = "Insert" }, ["ix"] = { name = "INSERT", hl = "Insert" }, ["R"] = { name = "REPLACE", hl = "Replace" }, ["Rc"] = { name = "REPLACE", hl = "Replace" }, ["Rx"] = { name = "REPLACE", hl = "Replace" }, ["Rv"] = { name = "V-REPLACE", hl = "Replace" }, ["Rvc"] = { name = "V-REPLACE", hl = "Replace" }, ["Rvx"] = { name = "V-REPLACE", hl = "Replace" }, ["c"] = { name = "COMMAND", hl = "Command" }, ["cv"] = { name = "EX", hl = "Command" }, ["ce"] = { name = "EX", hl = "Command" }, ["r"] = { name = "REPLACE", hl = "Normal" }, ["rm"] = { name = "MORE", hl = "Normal" }, ["r?"] = { name = "CONFIRM", hl = "Normal" }, ["!"] = { name = "SHELL", hl = "Normal" }, ["t"] = { name = "TERMINAL", hl = "Command" }, } local mode = mode_settings[vim.fn.mode()] or {} return table.concat({ "%#StatuslineMode" .. mode.hl .. "Inverted" .. "#", "%#StatuslineMode" .. mode.hl .. "#" .. mode.name, "%#StatuslineMode" .. mode.hl .. "Inverted" .. "#", }) end</code></pre> We: Get the current mode using vim.fn.mode()</code></li> Get the corresponding display name and the highlight group</li> Construct a string complete with fancy icons for a bubble effect</li> </ul> We can then drop this component into our render()</code> function like so: return { render = function() local active_win = vim.fn.win_getid() local status_win = tonumber(vim.g.actual_curwin) if status_win ~= active_win then return "Statusline for inactive windows" end return table.concat({ mode_component(), -- <- New component added here "%=", "Statusline right-aligned stuff", }) end, }</code></pre> (Note: if you set the mode in the statusline, you might also want to :set noshowmode</code> so it doesn't get duplicated on the row below). This gets us something like this: Some gotchas</a></h2> Gotcha: statusline refresh If you use a component which updates in the background or with a slight delay, you may find that your statusline doesn't update, e.g. until you start modifying text. In these cases you can use :redrawstatus</code> to trigger an update. E.g. I found I needed to do this in an autocommand to make sure I got snappy updates from information provided by gitsigns.nvim</a>: vim.api.nvim_create_autocmd("User", { pattern = "GitSignsUpdate", group = vim.api.nvim_create_augroup("statusline_git", {}), command = "redrawstatus", })</code></pre>Final notes</a></h2> This is hopefully enough for you to begin to lovingly craft your own statusline that does exactly what you need and nothing more. If you want some more inspiration you can see the actual version I use</a>, which includes components for the current file, Git status, etc. Thanks to Evgeni Chasnovski for kindly pointing this out</a> in response to the first version of this post, which used the slightly less ergonomic %!</code> to evaluate Lua code in the statusline. ↩</a> </li> </ol> </section>}

Jacob Scott

Roll your own Neovim statusline