tabline.wez

Tabline supports various themes. You can set a theme by name (e.g., 'GruvboxDark') or use the WezTerm config colors object (config.colors).

To modify specific colors, use the theme_overrides option within options. Overrides can be applied per keytable (mode) or for general tab colors. Note that keytables must end with _mode (e.g., normal_mode, copy_mode).

Available Override Scopes:

• {mode_name}_mode: Overrides colors for sections a, b, and c for a specific mode.
• tab: Overrides active, inactive, and inactive_hover tab colors.

You can also change the theme dynamically after setup using tabline.set_theme().

-- Apply theme with specific overrides
tabline.setup({
  options = {
    theme = 'Catppuccin Mocha',
    theme_overrides = {
      normal_mode = {
        c = { bg = '#112233' },
      },
      tab = {
        active = { fg = '#89b4fa', bg = '#313244' },
      }
    }
  }
})

-- Change theme dynamically
tabline.set_theme('GruvboxDark')

You can create custom components using several methods:

1. Lua Functions: Pass a function that returns a string.
   • Tabline components receive (Window, Pane) as arguments.
   • Tab components receive (TabInformation, PaneInformation) as arguments.
2. Text Strings: Any string is automatically wrapped in a Text FormatItem.
3. WezTerm FormatItems: Pass a table of WezTerm format items (e.g., Attribute, Foreground, Background).
4. Lua Expressions: Use oneliners, global variables, or require statements.

-- 1. Lua Function
local function hello() return 'Hello World' end
sections = { tabline_a = { hello } }

-- 2. Text String
sections = { tabline_a = { 'Hello World' } }

-- 3. WezTerm FormatItems
sections = {
  tabline_c = {
    { Attribute = { Underline = 'Single' } },
    { Foreground = { AnsiColor = 'Fuchsia' } },
    'Hello World',
  }
}

-- 4. Lua Expression
sections = { tabline_c = { os.date('%a'), require('util').status() } }

Extensions allow you to change the tabline appearance based on events from other plugins. An extension is defined as a table containing:

• name: A unique string.
• events: A table defining show and hide events (can be a single string or a table of strings).
• delay (number): Seconds to wait before hiding (default 5).
• callback (function): Called when the show event triggers.
• sections: The sections to display when shown.
• colors: Overrides for the extension's section colors.

When a show event is triggered, the defined sections are displayed. If hide is not provided, sections hide after the delay.

local my_extension = {
  'my_extension_name',
  events = {
    show = 'my_plugin.show',
    hide = 'my_plugin.hide',
    delay = 3,
    callback = function(window) wezterm.log_info('Extension shown') end
  },
  sections = { tabline_a = { 'mode' } },
  colors = { a = { fg = '#181825', bg = '#f38ba8' } }
}

tabline.setup({ extensions = { my_extension } })

Components can have local options that override global defaults.

General Component Options

Available for all components:

• icons_enabled (bool): Enables/disables icons for this component.
• icons_only (bool): Only shows the icon if the component has one.
• icon (string|table): The icon to display. If a table, it can include align and color.
• cond (function): A condition function; component only loads if it returns true.
• padding (number|table): Padding for left/right. e.g., padding = { left = 0, right = 1 }.
• fmt (function): A formatter function receiving (string, Window/TabInformation).

Specific Component Examples

• datetime: style (format string), hour_to_icon (table mapping hours to icons).
• cwd / parent: max_length (integer).
• index: zero_indexed (bool).
• process: process_to_icon (table mapping process names to icons).
• cpu / ram: throttle (seconds), use_pwsh (bool).
• battery: battery_to_icon (table mapping levels to icons).
• domain: domain_to_icon (table mapping domains to icons).
• output: icon_no_output (icon to show when no unseen output exists).