ARCHIVED
I'm no longer using buftabline.nvim and don't plan on updating it, so I'm archiving this repository. I found that I was spending too much of my time managing my open buffers (something Vim doesn't want you to do) and that using standard tabpages and switching buffers via Telescope / FZF vastly sped up my editing. Adjusting to this workflow took time, but I recommend trying it before resorting to a buffer tabline plugin like this one.
To my knowledge, everything in this plugin works, so if it fits your needs, feel free to use it as-is or fork it.
buftabline.nvim
A low-config, minimalistic buffer tabline Neovim plugin written in Lua, shamelessly inspired by vim-buftabline.
Setup
Install using your favorite plugin manager and call the following Lua code somewhere in your configuration:
require("buftabline").setup {}If you're using packer.nvim, you can install and set up buftabline simultaneously:
use {
"jose-elias-alvarez/buftabline.nvim",
requires = {"kyazdani42/nvim-web-devicons"}, -- optional!
config = function() require("buftabline").setup {} end
}Features
Buftabline shows your open buffers in your tabline with (optional) filetype
icons and applies highlighting to each tab based its buffer's state. If you
want, it'll also show your tabpages (:help tabpages). That's pretty much it.
For convenience, the plugin exposes a function, buftarget(number, command)
which will target a buffer in the tabline with a command:
require("buftabline").buftarget(1, "rightbelow sb")By default, the plugin maps <Leader>0-9 to go to the corresponding buffer (0
gets converted to 10), but you can disable this by setting go_to_maps to
false (see Options).
To simplify the creation of more custom commands, buftabline also exposes a
map method. The following example will map <Leader>c1 through Leader<c9>
to the corresponding bdelete command:
require("buftabline").map({ prefix = "<Leader>c", cmd = "bdelete" })Lastly, the plugin adds the following Vim commands:
-
:ToggleBuftabline(useful for smaller screens / focus sessions) -
:BufNextand:BufPrev(like:bnextand:bprev, but they correspond to bufferline indexes.
Options
For most users, everything should work out-of-the-box, but the plugin exposes the following options (defaults shown):
local options = {
tab_format = " #{n}: #{b}#{f} ",
buffer_id_index = false,
icon_colors = true,
start_hidden = false,
auto_hide = false,
disable_commands = false,
go_to_maps = true,
flags = {
modified = " [+]",
not_modifiable = " [-]",
readonly = " [RO]",
},
hlgroups = {
current = "TabLineSel",
normal = "TabLine",
active = nil,
spacing = nil,
modified_current = nil,
modified_normal = nil,
modified_active = nil,
tabpage_current = nil,
tabpage_normal = nil,
},
show_tabpages = true,
tabpage_format = " #{n} ",
tabpage_position = "right",
}| Option | Description |
|---|---|
tab_format |
Defines how the plugin formats buffer tabs (see Format below for details). |
buffer_id_index |
Uses buffer numbers (the ones shown in :ls) instead of sequential indexes. |
icon_colors |
Shows icon colors in your tabline. Can be true (always show), current (show for current tab), and normal (show for background tabs). |
start_hidden |
Hides the tabline when Neovim starts. |
auto_hide |
Shows the tabline when you have more than one buffer open and hides it when you don't. Not compatible with start_hidden. |
disable_commands |
Stops the plugin from defining commands. |
go_to_maps |
Maps <Leader>0-9 to go to the corresponding buffer. |
flags |
Sets the flags used to mark a buffer's status. |
hlgroups |
Sets highlight groups (see Colors below for details). |
show_tabpages |
Shows tabpages (:h tabpages) in your bufferline. Can be true (show if more than one tabpage), always (always show), and false (disable). If you don't use tabpages, there's no need to change this. |
tabpage_format |
Defines how the plugin formats tabpages (see Format below for details). |
tabpage_position |
Determines where the plugin shows tabpages. Can be right or left. Does nothing if you've set show_tabpages to false. |
Format
The tab_format string accepts the following special options and replaces them
with the corresponding buffer information. The plugin won't do anything to other
characters, including spaces and separators.
| Option | Information |
|---|---|
#{n} |
The buffer's index. Modified by buffer_id_index. |
#{b} |
The buffer's filename. If two or more buffers share a filename, it'll add the name of each buffer's enclosing directory. |
#{f} |
The buffer's flags (modified, modifiable, and read-only). |
#{i} |
The buffer's filetype icon. |
The tabpage_format string accepts the following option:
| Option | Information |
|---|---|
#{n} |
The tabpage's index. |
Colors
The hlgroups option is a table that accepts the following keys to allow
setting highlight groups based on buffer state. Leaving a value empty will
cause the plugin to fall back to the next available group.
| Key | Condition |
|---|---|
current |
The current buffer. |
normal |
The buffer is not current visible in any window. |
active |
The buffer is visible in another window. |
spacing |
Applied to the empty space between buffer tabs and any right-aligned tabs (or the end of the viewport). |
modified_current |
Same as current, but the buffer is modified. |
modified_normal |
Same as normal, but the buffer is modified. |
modified_active |
Same as active, but the buffer is modified. |
tabpage_current |
The current tabpage. Falls back to current if not defined. |
tabpage_normal |
Tabpages other than the current. Falls back to normal if not defined. |
FAQ
How do I enable icons?
Add #{i} to tab_format. For example, to keep the default format but show
icons after the buffer's filename:
tab_format = " #{n}: #{b}#{f} #{i} "Non-goals
- Vim support. Use vim-buftabline!
- Mouse support.
- Visual customization beyond what's available now.
Aside from these, I'm open to PRs.
Tests
Run make test from the plugin's root directory. Depends on
plenary.nvim.
Inspiration
-
vim-buftabline, the direct inspiration for this plugin and still a solid plugin.
-
nvim-bufbar by @ojroques, who directed me to his plugin and encouraged me to use it as a starting point.
-
lightline-bufferline, which gave me the idea to "target" buffers in the tabline with commands.
-
nvim-bufferline and barbar.nvim, two tabline plugins that are far and away better than this one but are a little too much for my simple needs. (Thanks to barbar.nvim for its implementation of colored icons, which provided the basis for the implementation in this plugin.)