justline.nvim

Just a status line. No abstractions. No bloat. No dependencies. Just works.

A small Neovim statusline written in Lua, with a fixed layout and a colored mode indicator. Call setup() and get on with editing.

What it shows

The mode, file path, and modified flag sit on the left. File type, encoding, line-ending format, progress through the file, and cursor position sit on the right.

Field	Behavior
Mode	NORMAL, INSERT, VISUAL, V-LINE, V-BLOCK, REPLACE, COMMAND, or TERMINAL
File	Neovim's %f file path, followed by its %m modified/modifiable flag
File type	Neovim's %y, for example [lua]; empty when unset
Encoding	Buffer fileencoding, falling back to encoding
Line endings	Buffer fileformat in brackets, such as [unix]
Progress	Cursor position through the file, as a percentage of lines
Position	Line number and byte column, in line:column form

The statusline is global: one bar at the bottom of Neovim. Modes outside the explicit mode map display [?]. There are no icons or font dependencies, Git integrations, diagnostics, timers, or background jobs.

Requirements

Use Neovim 0.9 or newer as the documented baseline. The plugin reads highlight colors with nvim_get_hl(), introduced in 0.9. Older versions are not covered by this documentation; the highlight lookup itself has a fallback.

For the intended RGB colors, use a true-color terminal and enable:

vim.opt.termguicolors = true

The plugin does not change that option.

Installation

The repository is named justline.nvim; its Lua module is just_line.

The package contains these files:

• lua/just_line/init.lua (implementation)
• doc/justline.txt (Neovim help)
• README.md

Native Neovim packages

In Neovim, find the data directory for your active configuration:

:echo stdpath('data')

Place or clone the repository under that directory at:

site/pack/plugins/opt/justline.nvim/

For example, the implementation must end up at <data>/site/pack/plugins/opt/justline.nvim/lua/just_line/init.lua. Use the data path reported by the configuration in which you want the plugin.

Add this to your init.lua, preferably after selecting your colorscheme:

vim.cmd.packadd("justline.nvim")
require("just_line").setup()

If you use site/pack/plugins/start/justline.nvim/ instead, omit packadd and keep the setup() call.

Other plugin managers

Install the repository with your preferred manager, then run the following in its configuration callback, after it has made the plugin available:

require("just_line").setup()

Use an explicit callback if your manager infers module names from repository names: justline.nvim and just_line do not have the same spelling.

Setup and API

require("just_line").setup()

Enables the statusline. There are no configuration arguments or options.

Setup sets laststatus to 3, defines the plugin highlights, recreates the JustLine autocommand group, and assigns:

vim.opt.statusline = "%!v:lua.require'just_line'.statusline()"

ColorScheme refreshes the highlights; ModeChanged requests a statusline redraw. Calling setup() again reapplies these settings and replaces the group's autocommands instead of adding duplicates. It also overwrites any customizations to the plugin's highlight groups.

Requiring the module alone does not enable it. There are no user commands, key mappings, or disable function.

require("just_line").statusline()

Returns the statusline format string, including Neovim's % items and highlight switches. Neovim evaluates those items when drawing the bar. This function is the renderer used by setup(); it does not perform setup itself.

Colors

All plugin-defined groups are bold. Normal mode uses colors read from StatusLine. Other mode indicators use its background as their foreground, with fixed accent backgrounds. Cursor progress and position use the foreground read from LineNr.

Highlight group	Foreground	Background
StatusModeNormal	StatusLine.fg or #1d2021	StatusLine.bg or #a9b665
StatusModeInsert	StatusLine.bg or #1d2021	#7daea3
StatusModeVisual	StatusLine.bg or #1d2021	#d8a657
StatusModeReplace	StatusLine.bg or #1d2021	#ea6962
StatusModeCommand	StatusLine.bg or #1d2021	#e78a4e
StatusModeTerminal	StatusLine.bg or #1d2021	#89b482
StatusLinePos	LineNr.fg or #d3869b	Not explicitly set

The remaining fields use StatusLine. The implementation reads stored highlight attributes without resolving links or reverse-video styling. Missing color attributes use the fallbacks above, so colors may differ from a theme's visually rendered StatusLine or LineNr.

To override a highlight and keep it after a colorscheme change, register your callback after calling setup():

require("just_line").setup()

local function custom_colors()
  vim.api.nvim_set_hl(0, "StatusModeInsert", {
    fg = "#1d2021",
    bg = "#a9b665",
    bold = true,
  })
end

local group = vim.api.nvim_create_augroup("JustLineUserColors", { clear = true })
vim.api.nvim_create_autocmd("ColorScheme", {
  group = group,
  callback = custom_colors,
})
custom_colors()

Keep user callbacks in a separate group: setup() clears JustLine.

Help

After loading the package, generate its help tags if your installer has not already done so:

:helptags ALL
:help justline

See :help justline.setup(), :help justline-highlights, and :help justline-troubleshooting for reference details.

Troubleshooting

• module 'just_line' not found: Check the package layout and load an opt package with vim.cmd.packadd("justline.nvim") before calling require().
• The bar is missing or replaced: Inspect :verbose set laststatus? and :verbose set statusline?. Another plugin or configuration may overwrite either option; a window-local statusline can also take precedence.
• Right-hand fields are missing: Check available width and the active statusline value. The implementation includes progress and position, but Neovim can truncate the result when space is limited.
• An extra mode message appears: Optionally set vim.opt.showmode = false. justline.nvim does not change this setting.
• Colors differ from the theme: Check the highlight behavior above and termguicolors.