Skip to main content
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()

​
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),
    },
  },
}

Build docs developers (and LLMs) love

Get started for freeTalk to us