README.md

tabby.nvim

A highly configurable, and neovim style tabline plugin. Use your nvim tabs as a workspace multiplexer!

Compatibility and Versions

Compatibility has always been a key consideration for tabby.nvim. Since its inception during the Neovim 0.5 era, the landscape of plugin management and semantic versioning has not been widely adopted; hence, we have made every effort to maintain backward compatibility with each release.

However, since then, numerous Neovim APIs have been added, altered, or deprecated, and the design philosophy of tabby.nvim has also gone through several iterations. Maintaining complete backward compatibility has become increasingly challenging. Therefore, starting from this version, tabby.nvim will adhere to semantic versioning. Within the same major version, no breaking changes will be introduced.

At next major version, v3, tabby.nvim will cleaner all deprecated apis and remove all vimscript.

Features

Tabline, not bufferline

A line for the vim tab page, not for buffers. A tabpage in vim holds one or more windows(not buffers). You can easily switch between tab pages to have several collections of windows to work on different things.

Tabline can help you use multiple tabs. Meanwhile, the bufferline is simply an array of opened files. As a result, Bufferline limits the power of vim, especially when editing a large workspace with many opened files.

For example, you are writing a backend service:

- Tab1: nvim-tree, controller/user.go, entity/user.go
- Tab2: nvim-tree, pkg/cache.go, redis/client.go
- Tab3: Terminal
- Tab4: Neogit.nvim

Highly configurable

Tabby provides a highly configurable way to set up your personalized tabline. There is no DSL for config; you can write any lua codes following the type hint. But also, Tabby provides some presets for quick start and as your example.

Tab rename

You can rename a tab by Tabby rename_tab <tabname>. Display the tab name by tab.name() (reference: Tab) in your config. Config fallback name by Line-Option

Window picker

Use command Tabby pick_window to open a selector to pick window in tabpages. This picker use native neovim selector, you can use a general UI plugin to enhance the appearance.

Jump mode for tabs

Inspired by barbar.nvim. Type one key to jump to a tabpage.

Use command Tabby jump_to_tab to get into jump mode. In jump mode, each tab have a key which displayed in tabline by tab.jump_key(). You can check if in jump mode by tab.in_jump_mode(). (reference: Tab)

For example in your config:

tab.in_jump_mode() and tab.jump_key() or tab.number()

The jump char is also displayed in presets.

Playground

Want to try your new config with no fear? Want to reproduct/debug a problem? Want to contribute? Use the playground!

1. Clone this repository, or open the directory your plugin manager installed tabby.nvim.
2. Put your config in 'playground/config.lua'
3. Execute make play, into a temporary neovim to check the config.
4. Use make clear-play to clean the change.

Install

Use your favorite plugin manager or script to installing 'nanozuki/tabby.com'. If you use lazy.nvim, you can refer the following example:

{
  'nanozuki/tabby.nvim',
  -- event = 'VimEnter', -- if you want lazy load, see below
  dependencies = 'nvim-tree/nvim-web-devicons',
  config = function()
    -- configs...
  end,
}

You don't need lazy load since 'tabby.nvim' is not slow. If you really want, you can use VimEnter or VeryLazy or anything else you like. Some of them (like VeryLazy) will make the raw tabline render first, and re-render to tabby's line quickly.

Setup

Tabline option

At default, neovim only display tabline when there are at least two tab pages. If you want always display tabline:

vim.o.showtabline = 2

Save and restore in session

You can save and restore tab layout and tab names in session, by adding word tabpages(for layout) and globals(for tab names) to vim.opt.sessionoptions. This is a valid sessionoptions:

vim.opt.sessionoptions = 'curdir,folds,globals,help,tabpages,terminal,winsize'

Setup tabby.nvim

And you can setup your own tabline like this (check Customize for more details):

local theme = {
  fill = 'TabLineFill',
  -- Also you can do this: fill = { fg='#f2e9de', bg='#907aa9', style='italic' }
  head = 'TabLine',
  current_tab = 'TabLineSel',
  tab = 'TabLine',
  win = 'TabLine',
  tail = 'TabLine',
}
require('tabby').setup({
  line = function(line)
    return {
      {
        { '  ', hl = theme.head },
        line.sep('', theme.head, theme.fill),
      },
      line.tabs().foreach(function(tab)
        local hl = tab.is_current() and theme.current_tab or theme.tab
        return {
          line.sep('', hl, theme.fill),
          tab.is_current() and '' or '󰆣',
          tab.number(),
          tab.name(),
          tab.close_btn(''),
          line.sep('', hl, theme.fill),
          hl = hl,
          margin = ' ',
        }
      end),
      line.spacer(),
      line.wins_in_tab(line.api.get_current_tab()).foreach(function(win)
        return {
          line.sep('', theme.win, theme.fill),
          win.is_current() and '' or '',
          win.buf_name(),
          line.sep('', theme.win, theme.fill),
          hl = theme.win,
          margin = ' ',
        }
      end),
      {
        line.sep('', theme.tail, theme.fill),
        { '  ', hl = theme.tail },
      },
      hl = theme.fill,
    }
  end,
  -- option = {}, -- setup modules' option,
})

In recent versions, we use require('tabby.tabline').set(fn, opt?) to set up the tabline. You can continue to use this.

Examples and Gallery

These are some awesome examples shared by tabby.nvim users! Also welcome to share your own!

Discussions: show and tell

Presets

If you want to quick start? That's fine, you can Use Preset Configs. And you can use theme of lualine in presets.

Commands

• Tabby rename_tab <tabname>: Rename tab. Use name in line by tab.name() (ref: Tab). Config fallback name by Line-Option
• Tabby pick_window: Open a selector to pick window in tabpages.
• Tabby jump_to_tab: Get one key to jump to tabpage, each keys are displayed in tabline by tab.jump_key()

Key mapping example

Tabby uses native nvim tab, so you can directly use nvim tab operation. Maybe you want to map some operation. For example:

vim.api.nvim_set_keymap("n", "<leader>ta", ":$tabnew<CR>", { noremap = true })
vim.api.nvim_set_keymap("n", "<leader>tc", ":tabclose<CR>", { noremap = true })
vim.api.nvim_set_keymap("n", "<leader>to", ":tabonly<CR>", { noremap = true })
vim.api.nvim_set_keymap("n", "<leader>tn", ":tabn<CR>", { noremap = true })
vim.api.nvim_set_keymap("n", "<leader>tp", ":tabp<CR>", { noremap = true })
-- move current tab to previous position
vim.api.nvim_set_keymap("n", "<leader>tmp", ":-tabmove<CR>", { noremap = true })
-- move current tab to next position
vim.api.nvim_set_keymap("n", "<leader>tmn", ":+tabmove<CR>", { noremap = true })

And in fact, vim has some built-in keymapping, it's better to read :help tabline. Here are some useful mappings:

gt					*i_CTRL-<PageDown>* *i_<C-PageDown>*
		Go to the next tab page.  Wraps around from the last to the
		first one.
{count}gt	Go to tab page {count}.  The first tab page has number one.
g<Tab>		Go to previous (last accessed) tab page.
gT		Go to the previous tab page.  Wraps around from the first one
		to the last one.

The {count} is the number displayed in presets.

Customize

Customize tabby with require('tabby').setup(opts):

tabline.setup({opts})                                            *tabby.setup()*
    Set tabline renderer function

    Parameters: ~
      • {opts}   Options dict:
                 • line (funtion) required: renderer function, receive a line
                   (|tabby.object.line|), return a node (|tabby.object.node|).
                 • option (|LineOption|) optional: renderer option.

All you need is to provide a render function, that use the variable line (ref: Line) to complete tabline node (ref: Node). The line variable gathered all features the tabby provided. And you can use opt (ref: [Line Option](#Line Option)) to customize some behaviors.

The render function will be called every time the nvim redraws tabline. You can use any valid neovim lua code to contracture the Node in this function. For example, if you want display current directory in tabline, you can do like this:

require('tabby').setup({
  line = function(line)
    local cwd = ' ' .. vim.fn.fnamemodify(vim.fn.getcwd(), ':t') .. ' '
    return {
        {
            { cwd, hl = theme.head },
            line.sep('', theme.head, theme.line),
        },
        ".....",
    }
  end,
  option = {},
})

Line

line.tabs()                                                  *tabby.line.tabs()*

    Return: ~
        |tabby-tabs|, a helper object for all tabs.

line.wins()                                                  *tabby.line.wins()*

    Return: ~
        |tabby-wins|, a helper object for all wins.

line.wins_in_tab({tabid})                   *tabby.line.wins_in_tab().foreach()*

    Parameters: ~
        {tabid}      Number, tab id

    Return: ~
        |tabby-wins|, a helper object for all wins in specified tab.


line.bufs()                                        *tabby.line.bufs().foreach()*

    Return: ~
        |tabby-bufs|, a helper object for all bufs.

line.spacer()                                              *tabby.line.spacer()*
    Separation point between alignment sections. Each section will be separated
    by an equal number of spaces.

    Return: ~
        Node |tabby-node|, spacer node.

line.truncate_point()                              *tabby.line.truncate_point()*
    Separation point between alignment sections. Each section will be separated
    by an equal number of spaces.

    Return: ~
        Node |tabby-node|, spacer node.

line.sep({symbol}, {hl}, {back_hl})                           *tabby.line.sep()*
    Make a separator, and calculate highlight.

    Parameters: ~
        [  ██████████████   ]
           |          |     |
           symbol     hl    back_hl
        {symbol}    string, separator symbol
        {hl}        Highlight |tabby-highlight|, current highlight
        {back_hl}   Highlight |tabby-highlight|, highlight in back

    Return: ~
        Node |tabby-node|, sep node.

line.api                                                        *tabby.line.api*
    Tabby gathered some neovim lua api in this object. Maybe help you to build
    lines. Details: |tabby-api|.

Line Option

The default value of LineOption is:

{
    tab_name = {
        name_fallback = function(tabid)
            return "fallback name"
        end,
        override = nil,
    },
    buf_name = {
        mode = "'unique'|'relative'|'tail'|'shorten'",
        name_fallback = function(bufid)
          return '[No Name]'
        end,
        override = nil,
    }
}

• {tab_name}, option for name of tab
  • {name_fallback} (fun(tabid:number):string) Function, receive a tab id, return a string. If no name provided, use this function to get the name.
  • {override} (fun(tabid:number):string) Function, receive a tab id, return a string. If this function return a string, use this string as tab name.
• {buf_name}, option for name of window and buffer
  • {mode} (string) Mode of buffer name, see |tabby.buf_name|

tab_name

Use command Tabby rename_tab <tabname> to rename tab. Use tab.name() (ref: Tab) to add in your config.

Options:

• {name_fallback} (fun(tabid:number):string) Function, receive a tab id, return a string. If no name provided, use this function to get the name.
• {override} (fun(tabid:number):string) Function, receive a tab id, return a string. If this function return a string, use this string as tab name.

buf_name

buf_name used by both win.buf_name() and buf.name(). You can customize by option "mode", "name_fallback" and "override".

There are four mode of buffer name. If current directory is "~/project" and there are three buffers:

• "~/project/a_repo/api/user.py"
• "~/project/b_repo/api/user.py"
• "~/project/b_repo/api/admin.py"

the result of every mode are:

• unique: "a_repo/api/user.py", "b_repo/api/user.py", "admin.py"
• relative: "a_repo/api/user.py", "b_repo/api/user.py", "b_repo/api/admin.py"
• tail: "user.py", "user.py", "admin.py"
• shorten: "r/a/user.py", "r/b/user.py", "r/b/admin.py"

Options:

• {mode} (string) Mode of buffer name, described above.
• {name_fallback} (fun(bufid:number):string) Function, receive a buffer id, return a string. If no name provided, use this function to get the name.
• {override} (fun(bufid:number):string) Function, receive a buffer id, return a string. If this function return a string, use this string as buffer name.

Tabs

"Tabs" is a helper object for tabs.

tabs.tabs                                                      *tabby.tabs.tabs*
    An Array of Tab |tabby-tab| that contained in this object.

tabs.foreach({callback}, {arrts})

    Parameters: ~
        {callback}  (fun(tab:TabbyTab,i:number,count:number):TabbyNode)
                    Function, receive a Tab |tabby-tab|, index and number of
                    tabs, return a Node |tabby-node|. Skip render when return is
                    empty string.
        {attrs}     Additional attributes added to the returned node.

    Return: ~
        Node |tabby-node|, rendered result of all tabs.


tabs.filter({filter})                                      *tabby.tabs.filter()*
    Filter tabs by filter function.

    Parameters: ~
        {filter}  (fun(tab:TabbyTab):boolean)
                  Function, receive a Tab |tabby-tab|, return a boolean. Truely
                  tab will be add to result.

    Return: ~
        Tabs |tabby-tabs|, filtered tabs.

Tab

tab.id                                                            *tabby.tab.id*
    id of tab, tab handle for nvim api.

tab.current_win()                                       *tabby.ab.current_win()*

    Return: ~
        Win |tabby-win|, current window.

tab.wins()                                                    *tabby.tab.wins()*

    Return: ~
        An Array of Win |tabby-win|, current window.

tab.wins().foreach({callback})                      *tabby.tab.wins().foreach()*
    See |tabby.line.wins().foreach()|.

tab.number()                                                *tabby.tab.number()*

    Return: ~
        Number, tab's order, start from 1.

tab.is_current()                                        *tabby.tab.is_current()*

    Return: ~
        Boolean, if this tab is current tab.

tab.name()                                               *tabby.tabby.tab.name()*

    Return: ~
        String, tab name. If name is not set, use option
        ".tab_name.name_fallback()" in LineOption |tabby-line-option|.

tab.close_btn({symbol})                                  *tabby.tab.close_btn()*
    Make a close button of this tab.

    Parameters: ~
        {symbol}  String, a symbol of close button.

    Return: ~
        Node |tabby-node|, close button node.

tab.jump_key()                                            *tabby.tab.jump_key()*
    In jump mode, return a key to jump to this tab, otherwise return empty
    string.

    Return: ~
        String, a key to jump to this tab.

tab.in_jump_mode()                                    *tabby.tab.in_jump_mode()*
    Return: ~
        Boolean, if this tab is in jump mode.

Wins

"Wins" is a helper object for windows.

wins.wins                                                      *tabby.wins.wins*
    An Array of Win |tabby-win| that contained in this object.

wins.foreach({callback}, {arrts})                         *tabby.wins.foreach()*

    Parameters: ~
        {callback}  (fun(win:TabbyWin,i:number,count:number):TabbyNode)
                    Function, receive a Win |tabby-win|, index and number of
                    wins, return a Node |tabby-node|. Skip render when return is
                    empty string.
        {attrs}     Additional attributes added to the returned node.

    Return: ~
        Node |tabby-node|, rendered result of all wins.

wins.filter({filter})                                      *tabby.wins.filter()*
    Filter wins by filter function.

    Parameters: ~
        {filter}  (fun(win:TabbyWin):boolean)
                  Function, receive a Win |tabby-win|, return a boolean. Truely
                  win will be add to result.

    Return: ~
        Wins |tabby-wins|, filtered wins.

    Example: ~
      - Don't display NvimTree: >
            local function no_nvimtree(win)
              return not string.match(win.buf_name(), 'NvimTree')
            end
            ...
            line.wins().filter(no_nvimtree).foreach(function
              ...
            end)
<

Win

win.id                                                            *tabby.win.id*
    id of window, win handle for nvim api.

win.tab()                                                      *tabby.win.tab()*

    Return: ~
        Tab |tabby-tab|, tab of this window.

win.buf()                                                      *tabby.win.buf()*

    Return: ~
        Buf |tabby-buf|, buf of the window.

win.is_current()                                        *tabby.win.is_current()*

    Return: ~
        Boolean, if this window is current.

win.file_icon()                                          *tabby.win.file_icon()*
    Get file icon of filetype. You need to installed plugin
    'kyazdani42/nvim-web-devicons'.

    Return: ~
        Node |tabby-node|, file icon.

win.buf_name()                                                *tabby.win.name()*

    Return: ~
        String, buffer name of this window. You can customize the name by using
        option ".buf_name" in LineOption |tabby-line-option|.

Bufs

"Bufs" is a helper object for buffers.

bufs.bufs                                                      *tabby.bufs.bufs*
    An Array of Buf |tabby-buf| that contained in this object.

bufs.foreach({callback}, {arrts})                         *tabby.bufs.foreach()*

      Parameters: ~
          {callback}  (fun(buf:TabbyBuf,i:number,count:number):TabbyNode)
                      Function, receive a Buf |tabby-buf|, index and number of
                      bufs, return a Node |tabby-node|. Skip render when return is
                      empty string.
          {attrs}     Additional attributes added to the returned node.

      Return: ~
          Node |tabby-node|, rendered result of all bufs.

bufs.filter({filter})                                      *tabby.bufs.filter()*
    Filter bufs by filter function.

    Parameters: ~
        {filter}  (fun(buf:TabbyBuf):boolean)
                  Function, receive a Buf |tabby-buf|, return a boolean. Truely
                  buf will be add to result.

    Return: ~
        Bufs |tabby-bufs|, filtered bufs.

Buf

Object for buffer.

buf.id                                                            *tabby.buf.id*
    id of buffer, buffer handle for nvim api.


buf.is_current()                                        *tabby.buf.is_current()*

    Return: ~
        Boolean, if this buffer is a buffer of the current window.


buf.is_changed()                                        *tabby.buf.is_changed()*
    Get if buffer is changed.

    Return: ~
        boolean, true if there are unwritten changes, false if not
        <https://neovim.io/doc/user/options.html#'buftype'> for details.


buf.file_icon()                                          *tabby.buf.file_icon()*
    Get file icon of filetype. You need to installed plugin
    'kyazdani42/nvim-web-devicons'.

    Return: ~
        Node |tabby-node|, file icon.


buf.name()                                                    *tabby.buf.name()*

    Return: ~
        String, name of this buffer. You can customize the name by using
        option ".buf_name" in LineOption |tabby-line-option|.


buf.type()                                                    *tabby.buf.type()*
    Get buftype option.

    Return: ~
        buftype, normal buffer is an empty string. check |buftype| or
        <https://neovim.io/doc/user/options.html#'buftype'> for details.

Node

Node is the rendered unit for tabby. Node is a recursive structure. It can be:

• A string: "nvim"

• A Number: 12

• A table containing a Node or an array of Node, with an optional property 'hl' to set highlight. Example:

  -- node 1
  {
    "tab1", 100
    hl = "TabLineSel"
  }
  -- node 2
  {
    "text 1"
    {
        "text 2",
        hl = "Info",
    },
    "text3",
    hl = "Fill",
  }

Highlight

There are two ways to declare a highlight:

• Use the name of neovim highlight group: "TabLineSel"
• Define "background", "foreground" and "style" in lua table: { fg = "#000000", bg = "#ffffff" style = "bold" } . The "style" can be:
  • bold
  • underline
  • underlineline, double underline
  • undercurl, curly underline
  • underdot, dotted underline
  • underdash, dashed underline
  • strikethrough
  • italic

API

api.get_tabs()                                            *tabby.api.get_tabs()*
    Get all tab ids

api.get_tab_wins({tabid})                             *tabby.api.get_tab_wins()*
    Get an winid array in specified tabid.

api.get_current_tab()                              *tabby.api.get_current_tab()*
    Get current tab's id.

api.get_tab_current_win({tabid})               *tabby.api.get_tab_current_win()*
    Get tab's current win's id.

api.get_tab_number({tabid})                         *tabby.api.get_tab_number()*
    Get tab's number.

api.get_wins()                                            *tabby.api.get_wins()*
    Get all windows, except floating window.

api.get_win_tab({winid})                               *tabby.api.get_win_tab()*
    Get tab id of specified window.

api.is_float_win({winid})                             *tabby.api.is_float_win()*
    Return true if this window is floating.

api.is_not_float_win({winid})                     *tabby.api.is_not_float_win()*
    Return true if this window is not floating.

api.get_bufs()                                            *tabby.api.get_bufs()*
    Get all listed buf ids

Use Presets

You can use presets for a quick start. The preset config uses nerdfont, and you should use a nerdfont-patched font to display that correctly.

To use preset, you can use setup({ preset , option? }), for example:

require('tabby').setup({
  preset = 'active_wins_at_tail',
  option = {
    theme = {
      fill = 'TabLineFill',       -- tabline background
      head = 'TabLine',           -- head element highlight
      current_tab = 'TabLineSel', -- current tab label highlight
      tab = 'TabLine',            -- other tab label highlight
      win = 'TabLine',            -- window highlight
      tail = 'TabLine',           -- tail element highlight
    },
    nerdfont = true,              -- whether use nerdfont
    lualine_theme = nil,          -- lualine theme name
    tab_name = {
      name_fallback = function(tabid)
        return tabid
      end,
    },
    buf_name = {
      mode = "'unique'|'relative'|'tail'|'shorten'",
    },
  },
})

The {opt} is an optional parameter, including all option in Line Option. And has some extending options:

• {theme}, the example shows the default value.
• {nerdfont}, whether use nerdfont, default is true.
• {lualine_theme}, use lualine theme to make theme. if theme is set, this option will be ignored. default is empty.

There are five {name} of presets:

• active_wins_at_tail

  

  Put all windows' labels in active tabpage at end of whold tabline.

• active_wins_at_end

  Put all windows' labels in active tabpage after all tags label. In-active tabpage's window won't display.

  

• tab_with_top_win

  Each tab lab with a top window label followed. The top window is the focus window when you enter a tabpage.

  

• active_tab_with_wins

  Active tabpage's windows' labels is displayed after the active tabpage's label.

  

• tab_only

  No windows label, only tab. and use focus window to name tab