tabline.wez

A versatile and easy to use tab-bar written in Lua.

tabline.wez requires the WezTerm terminal emulator.

Tabline was greatly inspired by lualine.nvim, a statusline plugin for Neovim, and tries to use the same configuration format.

Contributing

Feel free to create an issue/PR if you want to see anything else implemented, or if you have some question or need help with configuration.

Screenshots

Here is a preview of what the tab-bar can look like.

Some more examples, but very zoomed in.

tabline.wez supports all the same themes as WezTerm. You can find the list of themes here.

Installation

WezTerm Plugin API

local tabline = wezterm.plugin.require("https://github.com/michaelbrusegard/tabline.wez")

You'll also need to have a patched font if you want icons.

Type Support

For better development experience (autocompletion, type checking), you can use wezterm-types. It includes type definitions for tabline.wez.

Usage and customization

Tabline has sections as shown below just like lualine with the addition of tabs in the middle.

+-------------------------------------------------+
| A | B | C |  TABS                   | X | Y | Z |
+-------------------------------------------------+

Each sections holds its components e.g. Current active keytable (mode).

Configuring tabline in wezterm.lua

Default configuration

tabline.setup({
  options = {
    icons_enabled = true,
    theme = 'Catppuccin Mocha',
    tabs_enabled = true,
    theme_overrides = {},
    section_separators = {
      left = wezterm.nerdfonts.pl_left_hard_divider,
      right = wezterm.nerdfonts.pl_right_hard_divider,
    },
    component_separators = {
      left = wezterm.nerdfonts.pl_left_soft_divider,
      right = wezterm.nerdfonts.pl_right_soft_divider,
    },
    tab_separators = {
      left = wezterm.nerdfonts.pl_left_hard_divider,
      right = wezterm.nerdfonts.pl_right_hard_divider,
    },
  },
  sections = {
    tabline_a = { 'mode' },
    tabline_b = { 'workspace' },
    tabline_c = { ' ' },
    tab_active = {
      'index',
      { 'parent', padding = 0 },
      '/',
      { 'cwd', padding = { left = 0, right = 1 } },
      { 'zoomed', padding = 0 },
    },
    tab_inactive = { 'index', { 'process', padding = { left = 0, right = 1 } } },
    tabline_x = { 'ram', 'cpu' },
    tabline_y = { 'datetime', 'battery' },
    tabline_z = { 'domain' },
  },
  extensions = {},
})

If you want to get your current tabline config, you can do so with:

tabline.get_config()

WezTerm configuration

Tabline requires that some options are applied to the WezTerm Config struct. For example the retro tab-bar must be enabled. Tabline provides a function to apply some recommended options to the config. If you already set these options in your wezterm.lua you do not need this function. This needs to be called after tabline.setup().

tabline.apply_to_config(config)

[!CAUTION] This function has nothing to do with the tabline config passed into setup and retrieved with tabline.get_config(). It only applies some recommended options to the WezTerm config. More info here

Starting tabline

tabline.setup()

Setting a theme

options = { theme = 'GruvboxDark' }

All available themes are found here. Tabline uses get_builtin_schemes() under the hood, and not all the color schemes in WezTerm supplies the colors that some of the extensions for Tabline require. To get around this it is also possible to input your own colors from the WezTerm config or a completely custom colors scheme object.

options = { theme = config.colors } -- This is the WezTerm config colors object

Customizing themes

To modify a theme, you can use the theme_overrides option.

-- Change the background of tabline_c section for normal mode
tabline.setup({
  options = {
    theme_overrides = {
      normal_mode = {
        c = { bg = '#112233' },
      },
    }
  }
})

This is also where you would specify the colors for a new Key Table (mode). Tabline expects each key table to end with _mode.

tabline.setup({
  options = {
    theme_overrides = {
    -- Default colors from Catppuccin Mocha
      normal_mode = {
        a = { fg = '#181825', bg = '#89b4fa' },
        b = { fg = '#89b4fa', bg = '#313244' },
        c = { fg = '#cdd6f4', bg = '#181825' },
      },
      copy_mode = {
        a = { fg = '#181825', bg = '#f9e2af' },
        b = { fg = '#f9e2af', bg = '#313244' },
        c = { fg = '#cdd6f4', bg = '#181825' },
      },
      search_mode = {
        a = { fg = '#181825', bg = '#a6e3a1' },
        b = { fg = '#a6e3a1', bg = '#313244' },
        c = { fg = '#cdd6f4', bg = '#181825' },
      },
      -- Defining colors for a new key table
      window_mode = {
        a = { fg = '#181825', bg = '#cba6f7' },
        b = { fg = '#cba6f7', bg = '#313244' },
        c = { fg = '#cdd6f4', bg = '#181825' },
      },
      -- Default tab colors
      tab = {
        active = { fg = '#89b4fa', bg = '#313244' },
        inactive = { fg = '#cdd6f4', bg = '#181825' },
        inactive_hover = { fg = '#f5c2e7', bg = '#313244' },
      }
    }
  }
})

Getting theme

If you want to get the current theme and its colors, you can do so with:

tabline.get_theme()

You will get an object like the theme_overrides object above, but with the addition of a colors property (the colors property is the colors object from the WezTerm config with every color found there).

[!TIP] This can be useful when creating your own components or extensions and you want to use the same colors as the current theme

Setting theme after setup

You can change the theme after setup using:

tabline.set_theme('GruvboxDark') -- Just change theme
-- or
tabline.set_theme('GruvboxDark', {  -- Change theme with overrides
  normal_mode = {
    a = { fg = '#000000', bg = '#ffffff' }
  }
})
-- or
tabline.set_theme({ -- Just apply new overrides to current theme
  normal_mode = {
    a = { fg = '#000000', bg = '#ffffff' }
  }
})

Tabs

You can disable overwriting tabs by setting tabs_enabled to false in the options table.

Separators

tabline defines three kinds of separators:

section_separators - separators between sections
component_separators - separators between the different components in sections
tab_separators - separators around tabs

options = {
  section_separators = {
    left = wezterm.nerdfonts.pl_left_hard_divider,
    right = wezterm.nerdfonts.pl_right_hard_divider,
  },
  component_separators = {
    left = wezterm.nerdfonts.pl_left_soft_divider,
    right = wezterm.nerdfonts.pl_right_soft_divider,
  },
  tab_separators = {
    left = wezterm.nerdfonts.pl_left_hard_divider,
    right = wezterm.nerdfonts.pl_right_hard_divider,
  },
}

Here, left refers to the left-most sections (a, b, c), and right refers to the right-most sections (x, y, z). For the tabs it refers to each side of the tab.

Disabling separators

options = {
  section_separators = '',
  component_separators = '',
  tab_separators = '',
}

Changing components in tabline sections

sections = { tabline_a = { 'mode' } }

Available components

Tabline separates components into ones available for the tabline components (tabline_a, tabline_b, etc...), which are grouped under Window since they have access to the Window object.

And the tab_active and tab_inactive components which are grouped under Tab and have access to TabInformation.

Window
- mode (current keytable)
- battery (battery percentage)
- cpu (cpu percentage)
- datetime (current date and time)
- domain (current domain)
- hostname (hostname of the machine)
- ram (ram used in GB)
- window (window title)
- workspace (active wezterm workspace)
Tab
- tab (tab title)
- cwd (current working directory)
- output (indicator if tab has unseen output)
- parent (parent directory)
- process (process name)
- index (tab i

Tabline.wez

Install / Use

README