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:

  • 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):

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:

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 in strings field. Non-empty strings from strings 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.