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 and extends 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):

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.