bufferline.el - Documentation & Reference

INSTALLATION

Native package-vc

(use-package bufferline
                :vc (:url "https://github.com/szymonwilczek/bufferline.el")
                :config
                (global-bufferline-mode 1))

Elpaca

(use-package bufferline
                :ensure (:host github :repo "szymonwilczek/bufferline.el")
                :config
                (global-bufferline-mode 1))

Straight.el

(use-package bufferline
                :straight (:host github :repo "szymonwilczek/bufferline.el")
                :config
                (global-bufferline-mode 1))

Manual load-path

(use-package bufferline
                :load-path "~/path/to/bufferline.el"
                :config
                (global-bufferline-mode 1))

CONFIGURATION VARIABLES

Variable	Type	Default	Description
`bufferline-separator-style`	symbol	'vertical	Tab indicator style: 'vertical, 'bar, 'thick_bar, 'thin, 'thick, 'slant, 'slope, 'padded_slant, 'none.
`bufferline-indicator-width`	integer / nil	nil	Explicit pixel thickness for vertical indicator bars. nil uses default preset width.
`bufferline-indicator-face`	face	'default	Face used for indicator foreground color.
`bufferline-left-margin`	integer / string	8	Margin before first tab. Integer sets pixel width, string sets literal text.
`bufferline-top-padding`	integer	0	Top and bottom pixel padding for the entire tabline bar.
`bufferline-tab-padding-vertical`	integer	4	Vertical pixel padding for individual tabs.
`bufferline-tab-padding-horizontal`	integer / string	2	Horizontal trailing padding for individual tabs (space count or string).
`bufferline-icon-spacing`	integer / string	1	Spacing between file icon and buffer name.
`bufferline-sort-by`	symbol	'fifo	Buffer sorting strategy: 'fifo (visit history), 'name (alphabetical), 'extension, 'directory.
`bufferline-max-name-length`	integer	18	Maximum buffer name length before truncating with ellipsis.
`bufferline-show-buffer-icons`	boolean	t	Render filetype icons using nerd-icons.
`bufferline-icon-size`	float	0.85	Height scale factor for nerd-icons.
`bufferline-show-modified`	boolean	t	Display unsaved modification glyph.
`bufferline-modified-icon`	string	"●"	Glyph shown when buffer has unsaved changes.
`bufferline-show-read-only`	boolean	t	Display lock glyph on read-only buffers.
`bufferline-read-only-icon`	string	""	Glyph shown on read-only buffers.
`bufferline-show-pinned`	boolean	t	Display pin glyph on pinned buffers.
`bufferline-pinned-icon`	string	""	Glyph shown on pinned tabs.
`bufferline-show-trunc-markers`	boolean	t	Display overflow count badges and arrow markers when tabs exceed window width.
`bufferline-left-trunc-marker`	string	""	Left overflow indicator glyph.
`bufferline-right-trunc-marker`	string	""	Right overflow indicator glyph.
`bufferline-show-duplicate-prefix`	boolean	t	Prepend parent directory to disambiguate identical file names.
`bufferline-duplicate-prefix-depth`	integer	1	Directory depth levels to show for duplicate basenames.
`bufferline-show-diagnostics`	boolean	nil	Display Flymake diagnostic count badges.
`bufferline-diagnostics-error-icon`	string	""	Icon prefix for error diagnostics.
`bufferline-diagnostics-warning-icon`	string	""	Icon prefix for warning diagnostics.
`bufferline-diagnostics-info-icon`	string	""	Icon prefix for info diagnostics.
`bufferline-diagnostics-indicator`	function / nil	nil	Custom badge formatter function (lambda (buffer)).
`bufferline-numbers`	symbol / function	nil	Buffer numbering mode: 'ordinal, 'buffer-id, 'both, or custom function.
`bufferline-numbers-formatter`	string / function	"%d. "	Template string or custom formatter function (lambda (index buffer)).
`bufferline-show-special-buffers`	boolean	t	Whether to display special buffers (starting with '') such as scratch* or Messages. When nil, starred buffers are filtered out.
`bufferline-exclude-modes`	list	'(treemacs-mode ...)	Major modes where bufferline tab display is disabled.

INTERACTIVE COMMANDS

bufferline-next-tab: Switch cyclically to the next tab in active sort order.
bufferline-prev-tab: Switch cyclically to the previous tab in active sort order.
bufferline-close-tab: Close current or specified buffer without altering window split layout.
bufferline-toggle-pin: Toggle pinned state of current or specified buffer.
bufferline-pick: Interactively jump to a visible buffer using single-letter tags.
bufferline-pick-close: Interactively close a visible buffer using single-letter tags.

KEYBINDINGS INTEGRATION

Evil Mode Tab Navigation

(with-eval-after-load 'evil
                (define-key evil-normal-state-map (kbd "TAB") #'bufferline-next-tab)
                (define-key evil-normal-state-map (kbd "<tab>") #'bufferline-next-tab)
                (define-key evil-normal-state-map (kbd "<backtab>") #'bufferline-prev-tab)
                (define-key evil-normal-state-map (kbd "S-TAB") #'bufferline-prev-tab)
                (define-key evil-normal-state-map (kbd "<S-tab>") #'bufferline-prev-tab))

Leader Key Bindings (General / Evil)

(with-eval-after-load 'general
                (general-def :states 'normal :prefix "SPC"
                "b p" '(bufferline-pick :which-key "Pick Buffer")
                "b d" '(bufferline-pick-close :which-key "Pick Close Buffer")
                "b P" '(bufferline-toggle-pin :which-key "Toggle Pin Buffer")))

CREDITS

bufferline.nvim by akinsho ‐ visual layout inspiration and indicator design concepts.