--- *mini.statuscolumn* Statuscolumn --- --- MIT License Copyright (c) 2026 Evgeni Chasnovski --- Features: --- --- - Fast |'statuscolumn'| with improved defaults. --- - Fully customizable content via functions that take precomputed useful data. --- - |MiniStatuscolumn.gen_content.main()| for simplified customization. --- - Automatic dimming inside inactive windows content. --- --- Notes: --- - Works best on Neovim>=0.11. --- - Default content follows the behavior defined by options for the built-in --- statuscolumn sections. Like |'number'|, |'signcolumn'|, |'foldcolumn'|, etc. --- --- # Setup ~ --- --- This module needs a setup with `require('mini.statuscolumn').setup({})` --- (replace `{}` with your `config` table). It will create global Lua table --- `MiniStatuscolumn` which you can use for scripting or manually (with --- `:lua MiniStatuscolumn.*`). --- --- See |MiniStatuscolumn.config| for `config` structure and default values. --- --- # Suggested option values ~ --- --- - Default content works best with enabled |'number'| and |'signcolumn'|. --- --- - Depending on how distinctive |hl-FoldColumn| is from |hl-LineNr|, it might --- be a good idea to use minimal fold column characters in |'fillchars'|. --- Like `foldopen:🯘` and `foldclose:🮄`, while `foldsep` and `foldinner` (on --- Neovim>=0.12) set to a single space. --- --- # Comparisons ~ --- --- - [luukvball/statuscol.nvim](https://github.com/luukvbaal/statuscol.nvim): --- - A framework with building blocks and configuration: custom sections, --- sign filters, fold functions. --- While this module aims to provide a performant |'statuscolumn'| with --- a sensible default with a limited (yet enough) customization and an --- entry point to building own |'statuscolumn'|. --- --- - [folke/snacks.nvim#statuscolumn](https://github.com/folke/snacks.nvim): --- - An opinionated |'statuscolumn'| implementation with a limited --- customization. --- While this module provides more opportunities for building custom --- implementation and more customization. --- --- # Highlight groups ~ --- *MiniStatuscolumn-hl-groups* --- --- - `MiniStatuscolumnDim` - dimmed column. By default is a dimmed |hl-LineNr|. --- - `MiniStatuscolumnDimCursor` - dimmed column at cursor line. --- - `MiniStatuscolumnSep` - separator of column and text. --- - `MiniStatuscolumnSepCursor` - separator of column and text at cursor line. ---@tag MiniStatuscolumn ---@diagnostic disable:discard-returns ---@diagnostic disable:unused-local local MiniStatuscolumn = {} local H = {} --- Module setup --- ---@param config table|nil Module config table. See |MiniStatuscolumn.config|. --- ---@usage >lua --- require('mini.statuscolumn').setup() -- use default config --- -- OR --- require('mini.statuscolumn').setup({}) -- replace {} with your config table --- < MiniStatuscolumn.setup = function(config) -- Export module _G.MiniStatuscolumn = MiniStatuscolumn -- Setup config config = H.setup_config(config) -- Apply config H.apply_config(config) -- Define behavior H.create_autocommands(config) -- Create default highlighting H.create_default_hl() end --- Defaults ~ ---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section) ---@text # Content ~ --- --- `config.content` is a table that defines |'statuscolumn'| content for active --- (`content.active`) and inactive (`content.inactive`) windows. Each content is --- a function that takes a single `data` argument with useful info about the --- current Neovim state (precomputed only when needed to improve performance) and --- should return a |'statusline'| like string. --- --- An input `data` argument is a table with the following fields: --- - `(number)` - identifier of a drawn buffer. --- - `(boolean)` - whether |hl-CursorLineNr| conditions are met. --- - `(boolean)` - whether |'foldcolumn'| has fixed width. --- - `(boolean)` - whether |'signcolumn'| has fixed width. --- - `(boolean)` - whether |'statuscolumn'| default content --- is empty. Useful to determine if anything should be drawn. --- - `(boolean)` - current value of |'cursorline'|. --- - `(string)` - current value of |'cursorlineopt'|. --- - `(string)` - current value of |'foldcolumn'|. --- - `(boolean)` - current value of |'number'|. --- - `(boolean)` - current value of |'relativenumber'|. --- - `(string)` - current value of |'signcolumn'|. --- - `(number)` - identifier of a drawn window. --- --- The data about target line (for which content is evaluated) can be accessed --- as described in |'statuscolumn'| via the dedicated |v:| variables. --- Like |v:lnum|, |v:relnum|, and |v:virtnum|. --- --- Example custom content: >lua --- --- -- Show sign and separator if statuscolumn is not empty --- local active = function(data) --- return data.is_statuscolumn_empty and '' or '%s│' --- end --- -- Show nothing in inactive windows --- local inactive = function(_) return '' end --- local content = { active = active, inactive = inactive } --- require('mini.statuscolumn').setup({ content = content }) --- < --- If one content function is missing, the other is used in its place. --- If both content functions are missing, the default content is used: the output --- of |MiniStatuscolumn.gen_content.main()| with the following specification: >lua --- --- { fold = '%C', lnum = '%l', sign = '%s' }, -- Default sections --- { format = '=lfs', sep = 'ā–' }, -- Line-fold-sign-separator format --- { ltype = 'virt', lnum = '•' }, -- Dot in virtual lines --- { ltype = 'wrap', lnum = '↳' }, -- Arrow in wrapped lines --- { win = 'inactive', sep = ' ' }, -- No separator in inactive windows --- < --- Default content works best with enabled |'number'|, otherwise statuscolumn width --- might fluctuate if there are wrapped or virtual lines due to special symbols. --- --- Notes: --- - Make sure that custom content functions are as fast as possible since they --- will be called VERY frequently: at least every non-pure-cursor-move redraw --- (during typing, window scroll, etc.) for every visible line in every visible --- window. A rough estimate: about 100 times per redraw and about 1 million --- times per hour of text editing. --- - For performance reasons there are several |'statuscolumn'| optimizations --- that affect any implementation. Like pre-computed width and when it changes. --- Make sure to read |'statuscolumn'| to be aware of them. --- --- # Dim inactive windows ~ --- --- `config.dim` is a boolean that defines whether to dim statuscolumn content --- in inactive windows. It means that all |'statuscolumn'| relevant highlight --- groups are overridden to be `MiniStatuscolumnDimCursor` at cursor line and --- `MiniStatuscolumnDim` everywhere else. Default: `true`. --- --- Default values of dimming highlight groups are computed as a dimmed variant --- of |hl-LineNr| group, meaning its foreground is computed to be closer to its --- background. The used approach is good enough, if not - define groups manually. MiniStatuscolumn.config = { -- Statuscolumn content as functions that return statusline-like string content = { -- Content of an active window active = nil, -- Content of an inactive window inactive = nil, }, -- Whether to dim column content in inactive windows dim_inactive = true, } --minidoc_afterlines_end --- Content generators --- --- This is a table with function elements. Call to actually get a content table. MiniStatuscolumn.gen_content = {} --- Main content generator --- --- Generates a content that can be customized via selected "info" fields applied --- at selected drawn line "coordinates". --- --- "Info" string fields (as |'statusline'| like text): --- - - fold section. Default: `'%C'`. --- - - sign section. Default: `'%s'`. --- - - line number section. Default: `'%l'`. --- - - separator between column and in-buffer text. Default: `' '`. --- Highlighted with groups `MiniStatuscolumnSep` and `MiniStatuscolumnSepCursor` --- The latter is used under the conditions described in |hl-CursorLineNr|. --- - - order of sections (excluding ) as a string containing only --- `f` (fold), `s` (sign), `l` (lnum), and `=` (as `%=` in |'statusline'| syntax). --- Default: `'fs=l'`. --- --- NOTE: using dedicated |'statusline'| syntax, as in default values, makes --- section content follow their respective options. Like using `%l` will show --- nothing if |'number'| is disabled. --- --- "Coordinate" fields: --- - - type of drawn window. One of `'active'`, `'inactive'`. --- - - position of drawn line relative to the cursor. One of `'cursor'`, --- `'above'`, `'below'`. Note: value does not depend on the |'relativenumber'|, --- unlike |hl-LineNrAbove| and |hl-LineNrBelow|. --- - - type of drawn line. One of `'text'` (next to the regular buffer --- text), `'virt'` (next to the virtual line), `'wrap'` (next to the wrapped part --- of buffer text). --- --- Customization is done via an array specification that acts as a sequence of --- rules applied on top of the previous ones. Each rule/item should define at --- least one "info" field and may filter by one or more "coordinate" field. --- It is recommended to start with wider rules and go towards narrower ones. --- If an "info" field is not defined after all rules are processed, its --- default value is used. --- --- Each section is clickable with mouse. Clicks will be processed with an --- `opts.click` function and can be customized per section-coordinate. --- --- Examples of content specification: --- --- - Specification for default `content` in |MiniStatuscolumn.config|. --- Use as a template to adjust/remove added behavior: >lua --- --- local statuscolumn = require('mini.statuscolumn') --- local spec = { --- -- Prefer visible separator with a more efficient order to use --- -- usually present whitespace to the right of signs --- { format = '=lfs', sep = 'ā–' }, --- -- Use custom symbol for virtual lines --- { ltype = 'virt', lnum = '•' }, --- -- Use custom symbol for wrapped lines --- { ltype = 'wrap', lnum = '↳' }, --- -- Hide separator to better indicate inactive windows --- { win = 'inactive', sep = ' ' }, --- } --- statuscolumn.setup({ content = statuscolumn.gen_content.main(spec) }) --- < --- - Ways to configure separator: --- --- - Thicker separator at cursor: `{ pos = 'cursor', sep = 'ā–' }`. --- --- - More cell-centered separator: `{ format='=fsl', sep='│' }` --- --- - Ways to indicate inactive windows: --- --- - Hide regular non-cursor line: define `MiniStatuscolumnDim` highlight group --- to have the same foreground and background. It will still show cursor line --- and lines which have signs or line number with special highlighting (like --- diagnostics, diff status, etc.). --- --- - Show nothing: `{ win='inactive', fold='', lnum='', sign='' }` --- --- - Hide separator: `{ win='inactive', sep='' }` --- --- - Force highlighting: `{ pos='cursor', ltype='virt', lnum='%#CursorLineNr#•' }`. --- Has problems that it overrides highlighting from extmarks. --- --- Notes: --- - Implementation of |'statuscolumn'| has some performance trade-offs when it --- comes to computing which areas are clickable. Suggested usage: --- - Use one per window type, as section order is better to persist --- across lines of the same window. --- - Clicking the cell that contains text should work. Clicking an empty cell --- of known section might not always work. --- - On Neovim<0.13 the `ltype` is always the one that is used in the top --- window line. --- ---@param spec table[]|nil Specification array. Default: `{}`, which imitates --- default |'statuscolumn'|. ---@param opts table|nil Options. Possible fields: --- - `(function)` - action to perform on mouse click in statuscolumn. --- Default: |MiniStatuscolumn.default_click()|. --- --- Called with a single table `data` argument with the following fields: --- -