Tab Object

API reference for the Tab (MuxTab) object in WezTerm’s Lua configuration

The Tab object is also known as MuxTab in the WezTerm codebase. Available since version 20220624-141144-bd1b7c5d.

A MuxTab object represents a tab that is managed by the WezTerm multiplexer. It contains one or more panes arranged in a layout and provides methods to manage those panes and the tab’s state.

Tab objects cannot be created directly in Lua; they are typically accessed through window methods or event callbacks.

How to Access

Tab objects are commonly accessed through:

• The window:active_tab() method
• The pane:tab() method
• Event callbacks
• The wezterm.mux module

local wezterm = require 'wezterm'

wezterm.on('update-status', function(window, pane)
  local tab = window:active_tab()
  if tab then
    local title = tab:get_title()
  end
end)

Identification

tab:tab_id()

Returns the unique tab identifier.

Returns: number - The tab ID

local id = tab:tab_id()

Navigation Methods

tab:window()

Returns the MuxWindow object that contains this tab.

Returns: MuxWindow | nil

local window = tab:window()
if window then
  window:set_title('My Window')
end

tab:active_pane()

Returns the currently active pane in this tab.

Returns: Pane | nil

local pane = tab:active_pane()
if pane then
  local cwd = pane:get_current_working_dir()
end

tab:panes()

Returns an array of all panes in this tab (ignoring zoom state).

Returns: Pane[]

local panes = tab:panes()
wezterm.log_info('Tab has ', #panes, ' panes')

for i, pane in ipairs(panes) do
  local title = pane:get_title()
  wezterm.log_info('Pane ', i, ': ', title)
end

tab:panes_with_info()

Returns an array of panes with extended layout information.

Returns: Array of tables, each containing:

index · number

The topological pane index

is_active · boolean

Whether this is the active pane in the tab

is_zoomed · boolean

Whether this pane is zoomed

left · number

X offset from top-left of tab, in cells

top · number

Y offset from top-left of tab, in cells

width · number

Width of the pane in cells

height · number

Height of the pane in cells

pixel_width · number

Width of the pane in pixels

pixel_height · number

Height of the pane in pixels

pane · Pane

The Pane object

local panes_info = tab:panes_with_info()

for _, info in ipairs(panes_info) do
  wezterm.log_info(
    'Pane at (', info.left, ',', info.top, ') ',
    'size: ', info.width, 'x', info.height,
    ' active: ', info.is_active
  )
end

tab:get_pane_direction(direction)

Returns the pane in a specific direction relative to the active pane.

direction · string · required

Direction to search: “Left”, “Right”, “Up”, or “Down”

Returns: Pane | nil

local right_pane = tab:get_pane_direction('Right')
if right_pane then
  right_pane:activate()
end

Title Methods

tab:get_title()

Returns the title of the tab.

Returns: string

local title = tab:get_title()

tab:set_title(title)

Sets the title of the tab.

title · string · required

The new title for the tab

tab:set_title('My Custom Tab')

Size and Layout

tab:get_size()

Returns the size of the tab in cells.

Returns: Table with fields:

• rows - number of rows
• cols - number of columns
• pixel_width - width in pixels
• pixel_height - height in pixels
• dpi - DPI setting

local size = tab:get_size()
wezterm.log_info('Tab size: ', size.cols, 'x', size.rows)

tab:set_zoomed(zoomed)

Sets the zoom state of the active pane.

zoomed · boolean · required

Whether to zoom the active pane

Returns: boolean - The previous zoom state

-- Zoom the active pane
local was_zoomed = tab:set_zoomed(true)

-- Unzoom
tab:set_zoomed(false)

-- Toggle zoom
local is_zoomed = tab:set_zoomed(not was_zoomed)

Pane Rotation

tab:rotate_clockwise()

Rotates panes clockwise within the tab layout.

tab:rotate_clockwise()

Due to a bug in the implementation, this method currently rotates counter-clockwise despite its name.

tab:rotate_counter_clockwise()

Rotates panes counter-clockwise within the tab layout.

tab:rotate_counter_clockwise()

Activation

tab:activate()

Makes this tab the active tab in its window.

tab:activate()

Example: Tab Information Display

local wezterm = require 'wezterm'

wezterm.on('format-tab-title', function(tab_info)
  -- tab_info is TabInformation, but we can get the MuxTab
  local tab = wezterm.mux.get_tab(tab_info.tab_id)
  if not tab then
    return tab_info.tab_title
  end
  
  local panes = tab:panes()
  local active_pane = tab:active_pane()
  
  local title = string.format(
    '%s [%d panes]',
    tab:get_title(),
    #panes
  )
  
  return title
end)

Example: Navigate Between Panes

local wezterm = require 'wezterm'
local act = wezterm.action

return {
  keys = {
    {
      key = 'h',
      mods = 'CTRL|SHIFT',
      action = wezterm.action_callback(function(window, pane)
        local tab = pane:tab()
        local left_pane = tab:get_pane_direction('Left')
        if left_pane then
          left_pane:activate()
        end
      end),
    },
  },
}

Example: Layout Inspector

local wezterm = require 'wezterm'

wezterm.on('user-var-changed', function(window, pane, name, value)
  if name == 'INSPECT_LAYOUT' then
    local tab = pane:tab()
    local size = tab:get_size()
    local panes_info = tab:panes_with_info()
    
    wezterm.log_info('Tab size: ', size.cols, 'x', size.rows)
    wezterm.log_info('Panes: ', #panes_info)
    
    for i, info in ipairs(panes_info) do
      wezterm.log_info(
        string.format(
          'Pane %d: pos=(%d,%d) size=%dx%d active=%s zoomed=%s',
          i,
          info.left,
          info.top,
          info.width,
          info.height,
          tostring(info.is_active),
          tostring(info.is_zoomed)
        )
      )
    end
  end
end)

Example: Zoom Toggle with Indicator

local wezterm = require 'wezterm'

wezterm.on('update-status', function(window, pane)
  local tab = pane:tab()
  local panes_info = tab:panes_with_info()
  
  -- Check if any pane is zoomed
  local is_zoomed = false
  for _, info in ipairs(panes_info) do
    if info.is_zoomed then
      is_zoomed = true
      break
    end
  end
  
  if is_zoomed then
    window:set_left_status('ZOOMED ')
  else
    window:set_left_status('')
  end
end)

return {
  keys = {
    {
      key = 'z',
      mods = 'CTRL|SHIFT',
      action = wezterm.action_callback(function(window, pane)
        local tab = pane:tab()
        local panes_info = tab:panes_with_info()
        local is_zoomed = false
        
        for _, info in ipairs(panes_info) do
          if info.is_zoomed then
            is_zoomed = true
            break
          end
        end
        
        tab:set_zoomed(not is_zoomed)
      end),
    },
  },
}