mini.tabline documentation
Generated from the main
branch of ‘mini.nvim’
mini.tabline Tabline
MIT License Copyright (c) 2021 Evgeni Chasnovski
Module
Key idea: show all listed buffers in readable way with minimal total width.
Features:
Buffers are listed in the order of their identifier (see bufnr()).
Different highlight groups for “states” of buffer affecting ‘buffer tabs’.
Buffer names are made unique by extending paths to files or appending unique identifier to buffers without name.
Current buffer is displayed “optimally centered” (in center of screen while maximizing the total number of buffers shown) when there are many buffers open.
‘Buffer tabs’ are clickable if Neovim allows it.
Extra information section in case of multiple Neovim tabpages.
Truncation symbols which show if there are tabs to the left and/or right. Exact characters are taken from ‘listchars’ global value (
precedes
andextends
fields) and are shown only if ‘list’ option is enabled.
What it doesn’t do:
- Custom buffer order is not supported.
Dependencies
Suggested dependencies (provide extra functionality, will work without them):
- Enabled mini.icons module to show icons near file names. Falls back to nvim-tree/nvim-web-devicons or shows nothing.
Setup
This module needs a setup with require('mini.tabline').setup({})
(replace {}
with your config
table). It will create global Lua table MiniTabline
which you can use for scripting or manually (with :lua MiniTabline.*
).
See MiniTabline.config for config
structure and default values.
You can override runtime config settings locally to buffer inside vim.b.minitabline_config
which should have same structure as MiniTabline.config
. See mini.nvim-buffer-local-config for more details.
Suggested option values
Some options are set automatically by MiniTabline.setup():
- ‘showtabline’ is set to 2 to always show tabline.
Highlight groups
MiniTablineCurrent
- buffer is current (has cursor in it).MiniTablineVisible
- buffer is visible (displayed in some window).MiniTablineHidden
- buffer is hidden (not displayed).MiniTablineModifiedCurrent
- buffer is modified and current.MiniTablineModifiedVisible
- buffer is modified and visible.MiniTablineModifiedHidden
- buffer is modified and hidden.MiniTablineFill
- unused right space of tabline.MiniTablineTabpagesection
- section with tabpage information.MiniTablineTrunc
- truncation symbols indicating more left/right tabs.
To change any highlight group, set it directly with nvim_set_hl().
Disabling
To disable (show empty tabline), set vim.g.minitabline_disable
(globally) or vim.b.minitabline_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.
setup()
MiniTabline.setup
({config})
Module setup
Parameters
{config} (table|nil)
Module config table. See MiniTabline.config.
Usage
require('mini.tabline').setup() -- use default config
-- OR
require('mini.tabline').setup({}) -- replace {} with your config table
config
MiniTabline.config
Defaults
MiniTabline.config = {
-- Whether to show file icons (requires 'mini.icons')
show_icons = true,
-- Function which formats the tab label
-- By default surrounds with space and possibly prepends with icon
format = nil,
-- Where to show tabpage section in case of multiple vim tabpages.
-- One of 'left', 'right', 'none'.
tabpage_section = 'left',
}
Format
config.format
is a callable that takes buffer identifier and pre-computed label as arguments and returns a string with formatted label. Output will be treated strictly as text (i.e. no ‘statusline’ like constructs is allowed). This function will be called for all displayable in tabline buffers. Default: MiniTabline.default_format().
Example of adding “+” suffix for modified buffers:
function(buf_id, label)
local suffix = vim.bo[buf_id].modified and '+ ' or ''
return MiniTabline.default_format(buf_id, label) .. suffix
end
make_tabline_string()
MiniTabline.make_tabline_string
()
Make string for ‘tabline’
default_format()
MiniTabline.default_format
({buf_id}, {label})
Default tab format
Used by default as config.format
. Prepends label with padded icon based on buffer’s name (if show_icon
in MiniTabline.config is true
) and surrounds label with single space. Note: it is meant to be used only as part of format
in MiniTabline.config.
Parameters
{buf_id} (number)
Buffer identifier.
{label} (string)
Pre-computed label.
Return
(string)
Formatted label.