-
Notifications
You must be signed in to change notification settings - Fork 1
Usage_Tabline
Shawon edited this page Mar 14, 2025
·
1 revision
Usage guide for the tabline module.
The relevant files are shown below,
📂 bars.nvim
├── 🔐 ///////
├── 📂 lua
│ ├── 📂 bars
│ │ ├── 📂 components
│ │ │ ├── 📄 ////////////////
│ │ │ ├── 📄 //////////////
│ │ │ ├── 📄 tabline.lua # Components
│ │ │ └── 📄 //////////
│ │ ├── 📄 global.lua # Click functions
│ │ ├── 📄 ////////////////
│ │ ├── 📄 //////////////
│ │ ├── 📄 tabline.lua # Statuscolumn module
│ │ ├── 📄 utils.lua # Utilities
│ │ └── 📄 //////////
│ ├── 📄 ////////
│ └── 📂 definitions
│ ├── 📄 ////////
│ ├── 📄 ////////////////
│ ├── 📄 //////////////
│ ├── 📄 tabline.lua # Type definitions
│ └── 📄 //////////
├── 📂 plugin
│ └── 📄 ////////
└── 📄 /////////This module can be configured via the tabline option in require("bars").setup() or via require("bars.tabline").setup() directly.
Default configuration is given below,
See type definition
--- Configuration table for the tabline.
---@class tabline.config
---
--- Should tabline be set?
---@field condition? fun(): boolean
---
--- Default style.
---@field default? tabline.opts
---
--- Style named `string`.
---@field [string]? tabline.opts
--- Options for a tabline style.
---@class tabline.opts
---
--- Condition for this tabline.
--- Has no effect for `default`.
---@field condition? boolean | fun(): boolean
---
--- Components for the tabline.
---@field components tabline_component[]
---@alias tabline_component
---| tabline.components.tabs
---| tabline.components.bufs
---| tabline.components.empty
---| tabline.components.custom---@class tabline.config
tabline.config = {
default = {
components = {
---|fS
{ kind = "empty", hl = "Normal" },
{
kind = "tabs",
condition = function ()
return vim.g.__show_bufs ~= true;
end,
separator = " ",
separator_hl = "Normal",
overflow = " ┇ ",
overflow_hl = "Layer1I",
nav_left = " ",
nav_left_hl = "Color0",
nav_left_locked = " ",
nav_left_locked_hl = "Color1",
nav_right = " ",
nav_right_hl = "Color0",
nav_right_locked = " ",
nav_right_locked_hl = "Color1",
active = {
padding_left = " ",
padding_right = " ",
divider = " ┃ ",
win_count = " %d",
win_count_hl = nil,
-- bufname = " %s",
icon = " ",
hl = "Color4R"
},
inactive = {
padding_left = " ",
padding_right = " ",
divider = " | ",
icon = " ",
-- bufname = " %s",
hl = "Color0B"
}
},
{
kind = "bufs",
condition = function ()
return vim.g.__show_bufs == true;
end,
separator = " ",
separator_hl = "Normal",
overflow = " ┇ ",
overflow_hl = "Layer1I",
nav_left = " ",
nav_left_hl = "Color0",
nav_left_locked = " ",
nav_left_locked_hl = "Color1",
nav_right = " ",
nav_right_hl = "Color0",
nav_right_locked = " ",
nav_right_locked_hl = "Color1",
active = {
padding_left = " ",
padding_right = " ",
win_count = " ┃ %d",
win_count_hl = nil,
icon = "",
hl = "Color7R"
},
inactive = {
padding_left = " ",
padding_right = " ",
icon = "",
hl = "Color0B",
max_name_len = 10,
}
},
{ kind = "empty", hl = "Normal" },
---|fE
}
}
};By default, bars.nvim ships with a bunch of components. These components are,
Empty space.
See type definition
--- Empty tabline component.
---@class tabline.components.empty
---
--- Condition for this component.
---@field condition? fun(): boolean
---
--- Component type.
---@field kind "empty"
---
--- Highlight group for the component.
---@field hl? string{
kind = "empty",
hl = "Normal"
},List of open tabs.
Tip
This supports mouse clicks!
global.__tab_from_increase() & global.__tab_from_decrease() are used for left/right navigation.
%<n>T for switching to tabs.
See type definition
---@class tabline.components.tabs
---
--- Condition for this component.
---@field condition? fun(): boolean
---
--- Component type.
---@field kind "tabs"
---
--- Maximum number of tabs to show.
---@field max integer
---
--- List entry to start showing from.
---@field from integer
---
--- Text used to separate tabs.
---@field separator? string
--- Highlight group for the separator
---@field separator_hl? string
---
--- Text used to separate tabs.
---@field overflow? string
--- Highlight group for the separator
---@field overflow_hl? string
---
---
--- Text for the left navigation button.
---@field nav_left? string
--- Highlight group for the left navigation
--- button
---@field nav_left_hl? string
---
--- Text for the (locked) left navigation
--- button.
---@field nav_left_locked? string
--- Highlight group for the (locked) left
--- navigation button
---@field nav_left_locked_hl? string
---
---
--- Text for the right navigation button.
---@field nav_right? string
--- Highlight group for the right navigation
--- button
---@field nav_right_hl? string
---
--- Text for the (locked) right navigation
--- button.
---@field nav_right_locked? string
--- Highlight group for the (locked) right
--- navigation button
---@field nav_right_locked_hl? string
---
---@field active tabs.opts
---@field inactive tabs.opts
---@class tabs.opts
---
--- Format string to show window count
--- of a tab.
---@field win_count? string
---
--- Highlight group for window count.
---@field win_count_hl? string
---
--- Format string to show the current
--- buffer's name.
---@field bufname? string
---
--- Highlight group for the bufname.
---@field bufname_hl? string
---
--- Text to use between the bufname &
--- window count.
---@field divider? string
---@field divider_hl? string
---
---@field corner_left? string
---@field padding_left? string
---@field icon? string
---
---@field text? string
---
---@field padding_right? string
---@field corner_right? string
---
---
---@field hl? string
---
---@field corner_left_hl? string
---@field padding_left_hl? string
---@field icon_hl? string
---
---@field text_hl? string
---
---@field padding_right_hl? string
---@field corner_right_hl? string{
kind = "tabs",
condition = function ()
return vim.g.__show_bufs ~= true;
end,
separator = " ",
separator_hl = "Normal",
overflow = " ┇ ",
overflow_hl = "Layer1I",
nav_left = " ",
nav_left_hl = "Color0",
nav_left_locked = " ",
nav_left_locked_hl = "Color1",
nav_right = " ",
nav_right_hl = "Color0",
nav_right_locked = " ",
nav_right_locked_hl = "Color1",
active = {
padding_left = " ",
padding_right = " ",
divider = " ┃ ",
win_count = " %d",
win_count_hl = nil,
-- bufname = " %s",
icon = " ",
hl = "Color4R"
},
inactive = {
padding_left = " ",
padding_right = " ",
divider = " | ",
icon = " ",
-- bufname = " %s",
hl = "Color0B"
}
},List of open buffers
Tip
This has mouse support!
global.__buf_from_increase() & global.__buf_from_decrease() are used for left/right navigation.
global.__tabline_to_buf["B<n>"] for switching to buffers.
See type definition
--- List of buffers.
---@class tabline.components.bufs
---
--- Condition for this component.
---@field condition? fun(): boolean
---
--- Component type.
---@field kind "bufs"
---
--- Maximum number of tabs to show.
---@field max integer
---
--- Text to use for truncating long buffer name.
---@field truncate_symbol? string
---
--- List entry to start showing from.
---@field from integer
---
--- Text used to separate tabs.
---@field separator? string
--- Highlight group for the separator
---@field separator_hl? string
---
--- Text used to separate tabs.
---@field overflow? string
--- Highlight group for the separator
---@field overflow_hl? string
---
---
--- Text for the left navigation button.
---@field nav_left? string
--- Highlight group for the left navigation
--- button
---@field nav_left_hl? string
---
--- Text for the (locked) left navigation
--- button.
---@field nav_left_locked? string
--- Highlight group for the (locked) left
--- navigation button
---@field nav_left_locked_hl? string
---
---
--- Text for the right navigation button.
---@field nav_right? string
--- Highlight group for the right navigation
--- button
---@field nav_right_hl? string
---
--- Text for the (locked) right navigation
--- button.
---@field nav_right_locked? string
--- Highlight group for the (locked) right
--- navigation button
---@field nav_right_locked_hl? string
---
---@field active bufs.opts
---@field inactive bufs.opts
---@class bufs.opts
---
--- Should filetype icons be shown?
--- NOTE: Requires external dependency.
---@field ft_icon? boolean
---
--- Maximum length of buffer name.
---@field max_name_len? integer
---
--- Format string to show window count
--- of a buffer.
---@field win_count? string
---
--- Highlight group for window count.
---@field win_count_hl? string
---
--- Text to use between the bufname &
--- window count.
---@field divider? string
---@field divider_hl? string
---
---@field corner_left? string
---@field padding_left? string
---@field icon? string
---
---@field text? string
---
---@field padding_right? string
---@field corner_right? string
---
---
---@field hl? string
---
---@field corner_left_hl? string
---@field padding_left_hl? string
---@field icon_hl? string
---
---@field text_hl? string
---
---@field padding_right_hl? string
---@field corner_right_hl? string{
kind = "bufs",
condition = function ()
return vim.g.__show_bufs == true;
end,
separator = " ",
separator_hl = "Normal",
overflow = " ┇ ",
overflow_hl = "Layer1I",
nav_left = " ",
nav_left_hl = "Color0",
nav_left_locked = " ",
nav_left_locked_hl = "Color1",
nav_right = " ",
nav_right_hl = "Color0",
nav_right_locked = " ",
nav_right_locked_hl = "Color1",
active = {
padding_left = " ",
padding_right = " ",
win_count = " ┃ %d",
win_count_hl = nil,
icon = "",
hl = "Color7R"
},
inactive = {
padding_left = " ",
padding_right = " ",
icon = "",
hl = "Color0B",
max_name_len = 10,
}
},Custom component.
See type definition
---@class tabline.components.custom
---
--- Condition for this component.
---@field condition? fun(): boolean
---
--- Component type.
---@field kind "custom"
---
--- Text for this component.
---@field value string | fun(): string{
kind = "custom",
value = "Hello, Tabline!"
}Also in vimdoc, :h bars-tabline.