mini.statusline documentation
Generated from the main
branch of ‘mini.nvim’
mini.statusline Statusline
MIT License Copyright (c) 2021 Evgeni Chasnovski
Module
Features:
Define own custom statusline structure for active and inactive windows. This is done with a function which should return string appropriate for ‘statusline’. Its code should be similar to default one with structure:
Compute string data for every section you want to be displayed.
Combine them in groups with MiniStatusline.combine_groups().
Built-in active mode indicator with colors.
Sections can hide information when window is too narrow (specific window width is configurable per section).
Dependencies
Suggested dependencies (provide extra functionality, will work without them):
Nerd font (to support extra icons).
Enabled mini.icons module for MiniStatusline.section_fileinfo(). Falls back to using ‘nvim-tree/nvim-web-devicons’ plugin or shows nothing.
Enabled mini.git module for MiniStatusline.section_git(). Falls back to using ‘lewis6991/gitsigns.nvim’ plugin or shows nothing.
Enabled mini.diff module for MiniStatusline.section_diff(). Falls back to using ‘lewis6991/gitsigns.nvim’ plugin or shows nothing.
Setup
This module needs a setup with require('mini.statusline').setup({})
(replace {}
with your config
table). It will create global Lua table MiniStatusline
which you can use for scripting or manually (with :lua MiniStatusline.*
).
See MiniStatusline.config for config
structure and default values. For some content examples, see MiniStatusline-example-content.
You can override runtime config settings locally to buffer inside vim.b.ministatusline_config
which should have same structure as MiniStatusline.config
. See mini.nvim-buffer-local-config for more details.
Highlight groups
Highlight depending on mode (second MiniStatusline.section_mode() output):
MiniStatuslineModeNormal
- Normal mode.MiniStatuslineModeInsert
- Insert mode.MiniStatuslineModeVisual
- Visual mode.MiniStatuslineModeReplace
- Replace mode.MiniStatuslineModeCommand
- Command mode.MiniStatuslineModeOther
- other modes (like Terminal, etc.).
Highlight used in default statusline:
MiniStatuslineDevinfo
- for “dev info” group (MiniStatusline.section_git() and MiniStatusline.section_diagnostics()).MiniStatuslineFilename
- for MiniStatusline.section_filename() section.MiniStatuslineFileinfo
- for MiniStatusline.section_fileinfo() section.
Other groups:
MiniStatuslineInactive
- highliting in not focused window.
To change any highlight group, set it directly with nvim_set_hl().
Disabling
To disable (show empty statusline), set vim.g.ministatusline_disable
(globally) or vim.b.ministatusline_disable
(for a buffer) to true
. Considering high number of different scenarios and customization intentions, writing exact rules for disabling module’s functionality is left to user. See mini.nvim-disabling-recipes for common recipes.
Example content
Example content
Default content
This function is used as default value for active content:
function()
local mode, mode_hl = MiniStatusline.section_mode({ trunc_width = 120 })
local git = MiniStatusline.section_git({ trunc_width = 40 })
local diff = MiniStatusline.section_diff({ trunc_width = 75 })
local diagnostics = MiniStatusline.section_diagnostics({ trunc_width = 75 })
local lsp = MiniStatusline.section_lsp({ trunc_width = 75 })
local filename = MiniStatusline.section_filename({ trunc_width = 140 })
local fileinfo = MiniStatusline.section_fileinfo({ trunc_width = 120 })
local location = MiniStatusline.section_location({ trunc_width = 75 })
local search = MiniStatusline.section_searchcount({ trunc_width = 75 })
return MiniStatusline.combine_groups({
{ hl = mode_hl, strings = { mode } },
{ hl = 'MiniStatuslineDevinfo', strings = { git, diff, diagnostics, lsp } },
'%<', -- Mark general truncate point
{ hl = 'MiniStatuslineFilename', strings = { filename } },
'%=', -- End left alignment
{ hl = 'MiniStatuslineFileinfo', strings = { fileinfo } },
{ hl = mode_hl, strings = { search, location } },
})
end
Show boolean options
To compute section string for boolean option use variation of this code snippet inside content function (you can modify option itself, truncation width, short and long displayed names):
local spell = vim.wo.spell and (MiniStatusline.is_truncated(120) and 'S' or 'SPELL') or ''
Here x and y or z
is a common Lua way of doing ternary operator: if x
is true
-ish then return y
, if not - return z
.
setup()
MiniStatusline.setup
({config})
Module setup
Parameters
{config} (table|nil)
Module config table. See MiniStatusline.config.
Usage
require('mini.statusline').setup() -- use default config
-- OR
require('mini.statusline').setup({}) -- replace {} with your config table
config
MiniStatusline.config
Defaults
MiniStatusline.config = {
-- Content of statusline as functions which return statusline string. See
-- `:h statusline` and code of default contents (used instead of `nil`).
content = {
-- Content for active window
active = nil,
-- Content for inactive window(s)
inactive = nil,
},
-- Whether to use icons by default
use_icons = true,
}
active()
MiniStatusline.active
()
Compute content for active window
inactive()
MiniStatusline.inactive
()
Compute content for inactive window
combine_groups()
MiniStatusline.combine_groups
({groups})
Combine groups of sections
Each group can be either a string or a table with fields hl
(group’s highlight group) and strings
(strings representing sections).
General idea of this function is as follows;
String group is used as is (useful for special strings like
%<
or%=
).Each table group has own highlighting in
hl
field (if missing, the previous one is used) and string parts instrings
field. Non-empty strings fromstrings
are separated by one space. Non-empty groups are separated by two spaces (one for each highlighting).
Parameters
{groups} (table)
Array of groups.
Return
(string)
String suitable for ‘statusline’.
is_truncated()
MiniStatusline.is_truncated
({trunc_width})
Decide whether to truncate
This basically computes window width and compares it to trunc_width
: if window is smaller then truncate; otherwise don’t. Don’t truncate by default.
Use this to manually decide if section needs truncation or not.
Parameters
{trunc_width} (number|nil)
Truncation width. If nil
, output is false
.
Return
(boolean)
Whether to truncate.
section_mode()
MiniStatusline.section_mode
({args})
Section for Vim mode()
Short output is returned if window width is lower than args.trunc_width
.
Parameters
{args} (table)
Section arguments.
Return
(...)
Section string and mode’s highlight group.
section_git()
MiniStatusline.section_git
({args})
Section for Git information
Shows Git summary from mini.git (should be set up; recommended). To tweak formatting of what data is shown, modify buffer-local summary string directly as described in MiniGit-examples.
If ‘mini.git’ is not set up, section falls back on ‘lewis6991/gitsigns’ data or showing empty string.
Empty string is returned if window width is lower than args.trunc_width
.
Parameters
{args} (table)
Section arguments. Use args.icon
to supply your own icon.
Return
(string)
Section string.
section_diff()
MiniStatusline.section_diff
({args})
Section for diff information
Shows diff summary from mini.diff (should be set up; recommended). To tweak formatting of what data is shown, modify buffer-local summary string directly as described in MiniDiff-diff-summary.
If ‘mini.diff’ is not set up, section falls back on ‘lewis6991/gitsigns’ data or showing empty string.
Empty string is returned if window width is lower than args.trunc_width
.
Parameters
{args} (table)
Section arguments. Use args.icon
to supply your own icon.
Return
(string)
Section string.
section_diagnostics()
MiniStatusline.section_diagnostics
({args})
Section for Neovim’s builtin diagnostics
Shows nothing if diagnostics is disabled, no diagnostic is set, or for short output. Otherwise uses vim.diagnostic.get() to compute and show number of errors (‘E’), warnings (‘W’), information (‘I’), and hints (‘H’).
Short output is returned if window width is lower than args.trunc_width
.
Parameters
{args} (table)
Section arguments. Use args.icon
to supply your own icon. Use args.signs
to use custom signs per severity level name. For example:
{ ERROR = '!', WARN = '?', INFO = '@', HINT = '*' }
Return
(string)
Section string.
section_lsp()
MiniStatusline.section_lsp
({args})
Section for attached LSP servers
Shows number of LSP servers (each as separate “+” character) attached to current buffer or nothing if none is attached. Nothing is shown if window width is lower than args.trunc_width
.
Parameters
{args} (table)
Section arguments. Use args.icon
to supply your own icon.
Return
(string)
Section string.
section_filename()
MiniStatusline.section_filename
({args})
Section for file name
Show full file name or relative in short output.
Short output is returned if window width is lower than args.trunc_width
.
Parameters
{args} (table)
Section arguments.
Return
(string)
Section string.
section_fileinfo()
MiniStatusline.section_fileinfo
({args})
Section for file information
Shows ‘filetype’, ‘fileencoding’ / ‘encoding’, ‘fileformat’, and buffer size. Short output has only non-empty ‘filetype’ and is returned if window width is lower than args.trunc_width
or buffer is not normal (as per ‘buftype’).
Buffer size is computed based on current text, not file’s saved version.
If config.use_icons
is true and icon provider is present (see “Dependencies” section in mini.statusline), shows icon near the filetype.
Parameters
{args} (table)
Section arguments.
Return
(string)
Section string.
section_location()
MiniStatusline.section_location
({args})
Section for location inside buffer
Show location inside buffer in the form:
Normal:
'<cursor line>|<total lines>│<cursor column>|<total columns>'
Short:
'<cursor line>│<cursor column>'
Short output is returned if window width is lower than args.trunc_width
.
Parameters
{args} (table)
Section arguments.
Return
(string)
Section string.
section_searchcount()
MiniStatusline.section_searchcount
({args})
Section for current search count
Show the current status of searchcount(). Empty output is returned if window width is lower than args.trunc_width
, search highlighting is not on (see v:hlsearch), or if number of search result is 0.
args.options
is forwarded to searchcount(). By default it recomputes data on every call which can be computationally expensive (although still usually on 0.1 ms order of magnitude). To prevent this, supply args.options = { recompute = false }
.
Parameters
{args} (table)
Section arguments.
Return
(string)
Section string.