Skip to main content

​
Overview

Bufferline is a plugin that provides a sleek, customizable buffer and tab line at the top of your Neovim window. In the Magictt config, it’s configured to display tabs with a clean, minimal appearance.

​
What Bufferline Does

  • Tab Management: Displays open tabs at the top of the window
  • Visual Organization: Provides a clear view of all open tabs
  • Quick Navigation: Allows easy switching between tabs
  • Clean Interface: Minimal separator style for a streamlined look

​
Configuration

The bufferline configuration is minimal and focused: 
return {
  "akinsho/bufferline.nvim",
  dependencies = { "nvim-tree/nvim-web-devicons" },
  version = "*",
  opts = {
    options = {
      mode = "tabs",
      separator_style = "none",
    },
  },
}
Source: lua/magictt/plugins/bufferline.lua:1-12

​
Configuration Options

​
Mode: Tabs

mode = "tabs"
Bufferline is set to tabs mode, which means:
  • Shows Neovim tabs instead of individual buffers
  • Each tab can contain multiple windows
  • Cleaner when working with multiple files organized in tabs
  • Reduces clutter compared to showing every open buffer
Alternatively, you could use mode = "buffers" to show all open buffers instead of tabs.

​
Separator Style: None

separator_style = "none"
The separator between tabs is set to none for a minimal look:
  • No visual separators between tabs
  • Cleaner, more modern appearance
  • Tabs distinguished by background color instead
Other available separator styles:
  • "slant" - Slanted separators
  • "thick" - Thick line separators
  • "thin" - Thin line separators
  • { "any", "string" } - Custom separators

​
Usage

​
Visual Display

The bufferline appears at the very top of your Neovim window, showing:
  • Tab names (usually the file name or directory)
  • Active tab highlighted
  • Tab count if you have many tabs open
  • Icons based on file type (via nvim-web-devicons)

​
Tab Information

Each tab in the bufferline shows:
  • Icon: File type icon
  • Name: Tab name (typically the file name)
  • Modified indicator: Shows if file in tab has unsaved changes
  • Close button: Appears on hover (if configured)

​
Keybindings

Bufferline works with standard Neovim tab commands. The Magictt config provides these tab-related keybindings through which-key:

​
Tab Navigation

KeyActionDescription
<leader>tTab menuOpens tab-related commands
gtNext tabNative Neovim: Go to next tab
gTPrevious tabNative Neovim: Go to previous tab
{count}gtGo to tabNative Neovim: Go to specific tab number

​
Tab Management

CommandAction
:tabnewCreate new tab
:tabcloseClose current tab
:tabonlyClose all other tabs
:tabnextGo to next tab
:tabpreviousGo to previous tab
:tabfirstGo to first tab
:tablastGo to last tab
The <leader>t keybinding opens the which-key menu for tab-related commands.

​
Tab Workflow

​
Creating Tabs

  1. New empty tab: 
    :tabnew
  2. Open file in new tab: 
    :tabnew filename.lua
  3. Open current buffer in new tab: 
    <C-w>T
  1. Sequential navigation:
    • gt - Next tab
    • gT - Previous tab
  2. Direct navigation:
    • 1gt - Go to tab 1
    • 2gt - Go to tab 2
    • etc.
  3. First/Last tab: 
    :tabfirst
:tablast

​
Organizing Tabs

  1. Move tab position: 
    :tabmove 0    " Move to first position
:tabmove $    " Move to last position
:tabmove +1   " Move one position right
:tabmove -1   " Move one position left
  2. Close tabs: 
    :tabclose     " Close current tab
:tabonly      " Keep only current tab, close all others

​
Tips and Tricks

​
Switching to Buffer Mode

If you prefer to see individual buffers instead of tabs, edit lua/magictt/plugins/bufferline.lua:7: 
opts = {
  options = {
    mode = "buffers",  -- Changed from "tabs"
    separator_style = "none",
  },
}
After changing, restart Neovim or run :Lazy reload bufferline.nvim.

​
Adding Separators

For visual separation between tabs, change the separator style in lua/magictt/plugins/bufferline.lua:8: 
separator_style = "slant",  -- Changed from "none"
Options: "slant", "thick", "thin", or "none"

​
Tab Numbers

To show tab numbers for quick navigation: 
opts = {
  options = {
    mode = "tabs",
    separator_style = "none",
    numbers = "ordinal",  -- Shows 1, 2, 3...
  },
}
Other number options:
  • "none" - No numbers
  • "ordinal" - 1, 2, 3, 4…
  • "buffer_id" - Buffer ID numbers
  • "both" - Both ordinal and buffer ID

​
Close Button

To add close buttons to tabs: 
opts = {
  options = {
    mode = "tabs",
    separator_style = "none",
    close_command = "tabclose %d",
    show_close_icon = true,
  },
}

​
Diagnostics Integration

Show LSP diagnostics in the bufferline: 
opts = {
  options = {
    mode = "tabs",
    separator_style = "none",
    diagnostics = "nvim_lsp",
    diagnostics_indicator = function(count, level)
      local icon = level:match("error") and " " or " "
      return " " .. icon .. count
    end,
  },
}

​
Offsets for File Explorer

Create space for nvim-tree or other sidebar: 
opts = {
  options = {
    mode = "tabs",
    separator_style = "none",
    offsets = {
      {
        filetype = "NvimTree",
        text = "File Explorer",
        text_align = "center",
        separator = true,
      },
    },
  },
}

​
Mouse Support

Bufferline supports mouse clicks by default:
  • Left click: Switch to tab
  • Middle click: Close tab (if close command configured)
  • Right click: Context menu (if configured)

​
Grouping Tabs

Group related tabs together: 
opts = {
  options = {
    mode = "tabs",
    separator_style = "none",
    groups = {
      options = {
        toggle_hidden_on_enter = true,
      },
      items = {
        {
          name = "Tests",
          matcher = function(buf)
            return buf.name:match('_spec') or buf.name:match('_test')
          end,
        },
      },
    },
  },
}

​
Customization Examples

​
Minimal Configuration (Current)

The current Magictt configuration: 
opts = {
  options = {
    mode = "tabs",
    separator_style = "none",
  },
}

​
Enhanced Configuration

A more feature-rich configuration: 
opts = {
  options = {
    mode = "tabs",
    separator_style = "slant",
    numbers = "ordinal",
    close_command = "tabclose %d",
    show_close_icon = true,
    show_buffer_close_icons = true,
    diagnostics = "nvim_lsp",
    always_show_bufferline = true,
    offsets = {
      {
        filetype = "NvimTree",
        text = "File Explorer",
        text_align = "center",
        separator = true,
      },
    },
  },
}

​
Buffer Mode Configuration

For showing buffers instead of tabs: 
opts = {
  options = {
    mode = "buffers",
    separator_style = "none",
    show_buffer_close_icons = true,
    show_close_icon = false,
    always_show_bufferline = true,
  },
}

​
Troubleshooting

​
Bufferline Not Showing

If bufferline isn’t visible:
  1. Check if you have multiple tabs open: 
    :tabnew
  2. Ensure the plugin is loaded: 
    :Lazy
    Look for bufferline.nvim in the list.
  3. Try reloading the plugin: 
    :Lazy reload bufferline.nvim

​
Icons Not Displaying

If file type icons aren’t showing:
  1. Ensure you have a Nerd Font installed
  2. Configure your terminal to use the Nerd Font
  3. Verify nvim-web-devicons is installed: 
    :Lazy

​
Wrong Mode Displaying

If you’re seeing buffers instead of tabs (or vice versa):
  1. Check the mode setting in lua/magictt/plugins/bufferline.lua:7
  2. Ensure it’s set to "tabs" or "buffers" as desired
  3. Restart Neovim

​
External Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us