<h1 align="center"> bufferline.nvim </h1> A snazzy 💅 buffer line (with tabpage integration) for Neovim built using lua.

Demo GIF

Requirements
Installation
Usage
Configuration
Features
How do I see only buffers per tab?
Caveats
FAQ

This plugin shamelessly attempts to emulate the aesthetics of GUI text editors/Doom Emacs. It was inspired by a screenshot of DOOM Emacs using centaur tabs.

Requirements

Neovim 0.8+
A patched font (see nerd fonts)
A colorscheme (either your custom highlight or a maintained one somewhere)

Installation

It is advised that you specify either the latest tag or a specific tag and bump them manually if you'd prefer to inspect changes before updating. If you'd like to use an older version of the plugin compatible with nvim-0.6.1 and below please change your tag to tag = "v1.*"

Lua

-- using packer.nvim
use {'akinsho/bufferline.nvim', tag = "*", requires = 'nvim-tree/nvim-web-devicons'}

-- using lazy.nvim
{'akinsho/bufferline.nvim', version = "*", dependencies = 'nvim-tree/nvim-web-devicons'}

Vimscript

Plug 'nvim-tree/nvim-web-devicons' " Recommended (for coloured icons)
" Plug 'ryanoasis/vim-devicons' Icons without colours
Plug 'akinsho/bufferline.nvim', { 'tag': '*' }

Usage

See the docs for details :h bufferline.nvim

You need to be using termguicolors for this plugin to work, as it reads the hex gui color values of various highlight groups.

Vimscript

" In your init.lua or init.vim
set termguicolors
lua << EOF
require("bufferline").setup{}
EOF

Lua

vim.opt.termguicolors = true
require("bufferline").setup{}

You can close buffers by clicking the close icon or by right clicking the tab anywhere

Configuration

for more details on how to configure this plugin in details please see :h bufferline-configuration

Features

Colours derived from colorscheme where possible.
Sort buffers by extension, directory or pass in a custom compare function
Configuration via lua functions for greater customization.

Alternate styling

Slanted tabs

slanted tabs

NOTE: some terminals require special characters to be padded so set the style to padded_slant if the appearance isn't right in your terminal emulator. Please keep in mind though that results may vary depending on your terminal emulator of choice and this style might not work for all terminals

Sloped tabs

sloped tabs

see: :h bufferline-styling

Hover events

NOTE: this is only available for >= neovim 0.8+

hover-event-preview

see :help bufferline-hover-events for more information on configuration

Underline indicator

NOTE: as with the above your mileage will vary based on your terminal emulator. The screenshot above was achieved using kitty nightly (as of August 2022), with increased underline thickness and an increased underline position so it sits further from the text

Tabpages

This plugin can also be set to show only tabpages. This can be done by setting the mode option to tabs. This will change the bufferline to a tabline it has a lot of the same features/styling but not all.

A few things to note are

Sorting doesn't work yet as that needs to be thought through.
Grouping doesn't work yet as that also needs to be thought through.

LSP indicators

LSP Indicator

By setting diagnostics = "nvim_lsp" | "coc" you will get an indicator in the bufferline for a given tab if it has any errors This will allow you to tell at a glance if a particular buffer has errors.

In order to customise the appearance of the diagnostic count you can pass a custom function in your setup.

<details> <summary>snippet</summary>

-- rest of config ...

--- count is an integer representing total count of errors
--- level is a string "error" | "warning"
--- diagnostics_dict is a dictionary from error level ("error", "warning" or "info")to number of errors for each level.
--- this should return a string
--- Don't get too fancy as this function will be executed a lot
diagnostics_indicator = function(count, level, diagnostics_dict, context)
  local icon = level:match("error") and " " or " "
  return " " .. icon .. count
end

</details>

diagnostics_indicator

<details> <summary>snippet</summary>


diagnostics_indicator = function(count, level, diagnostics_dict, context)
  local s = " "
  for e, n in pairs(diagnostics_dict) do
    local sym = e == "error" and " "
      or (e == "warning" and " " or " ")
    s = s .. n .. sym
  end
  return s
end

</details>

The highlighting for the file name if there is an error can be changed by replacing the highlights for see:

:h bufferline-highlights

LSP indicators can additionally be reported conditionally, based on buffer context. For instance, you could disable reporting LSP indicators for the current buffer and only have them appear for other buffers.

diagnostics_indicator = function(count, level, diagnostics_dict, context)
  if context.buffer:current() then
    return ''
  end

  return ''
end

current visible

The first bufferline shows diagnostic.lua as the currently opened current buffer. It has LSP reported errors, but they don't show up in the bufferline. The second bufferline shows 500-nvim-bufferline.lua as the currently opened current buffer. Because the 'faulty' diagnostic.lua buffer has now transitioned from current to visible, the LSP indicator does show up.

Groups

bufferline_group_toggle

The buffers this plugin shows can be grouped based on a users configuration. Groups are a way of allowing a user to visualize related buffers in clusters as well as operating on them together e.g. by clicking the group indicator all grouped buffers can be hidden. They are partially inspired by google chrome's tabs as well as centaur tab's groups.

see :help bufferline-groups for more information on how to set these up

Sidebar offsets

explorer header

Numbers

bufferline with numbers

You can prefix buffer names with either the ordinal or buffer id, using the numbers option. Currently this can be specified as either a string of buffer_id | ordinal or a function

numbers

see :help bufferline-numbers for more details

Unique names

duplicate names

Close icons

close button

Re-ordering

re-order buffers

This order can be persisted between sessions (enabled by default).

Picking

bufferline pick

Pinning

Custom areas

custom area

see :help bufferline-custom-areas

How do I see only buffers per tab?

This behaviour is not native in neovim there is no internal concept of localis

Bufferline.nvim

Install / Use

README