> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# Tab Object

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

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

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

```lua theme={null}
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

```lua theme={null}
local id = tab:tab_id()
```

## Navigation Methods

### tab:window()

Returns the [MuxWindow](mux-window) object that contains this tab.

**Returns:** `MuxWindow | nil`

```lua theme={null}
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`

```lua theme={null}
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[]`

```lua theme={null}
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:

<ResponseField name="index" type="number">
  The topological pane index
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Whether this is the active pane in the tab
</ResponseField>

<ResponseField name="is_zoomed" type="boolean">
  Whether this pane is zoomed
</ResponseField>

<ResponseField name="left" type="number">
  X offset from top-left of tab, in cells
</ResponseField>

<ResponseField name="top" type="number">
  Y offset from top-left of tab, in cells
</ResponseField>

<ResponseField name="width" type="number">
  Width of the pane in cells
</ResponseField>

<ResponseField name="height" type="number">
  Height of the pane in cells
</ResponseField>

<ResponseField name="pixel_width" type="number">
  Width of the pane in pixels
</ResponseField>

<ResponseField name="pixel_height" type="number">
  Height of the pane in pixels
</ResponseField>

<ResponseField name="pane" type="Pane">
  The Pane object
</ResponseField>

```lua theme={null}
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.

<ParamField path="direction" type="string" required>
  Direction to search: "Left", "Right", "Up", or "Down"
</ParamField>

**Returns:** `Pane | nil`

```lua theme={null}
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`

```lua theme={null}
local title = tab:get_title()
```

### tab:set\_title(title)

Sets the title of the tab.

<ParamField path="title" type="string" required>
  The new title for the tab
</ParamField>

```lua theme={null}
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

```lua theme={null}
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.

<ParamField path="zoomed" type="boolean" required>
  Whether to zoom the active pane
</ParamField>

**Returns:** `boolean` - The previous zoom state

```lua theme={null}
-- 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.

```lua theme={null}
tab:rotate_clockwise()
```

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

### tab:rotate\_counter\_clockwise()

Rotates panes counter-clockwise within the tab layout.

```lua theme={null}
tab:rotate_counter_clockwise()
```

## Activation

### tab:activate()

Makes this tab the active tab in its window.

```lua theme={null}
tab:activate()
```

## Example: Tab Information Display

```lua theme={null}
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

```lua theme={null}
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

```lua theme={null}
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

```lua theme={null}
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),
    },
  },
}
```