> ## 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.

# Pane Key Actions

> Key assignments for splitting, navigating, and managing panes in WezTerm

## Overview

Panes allow you to divide a single tab into multiple terminal sessions. WezTerm provides comprehensive pane management through key assignments for splitting, navigating, resizing, and organizing panes.

## Creating Panes

### SplitHorizontal

Split the current pane horizontally (side by side):

```lua theme={null}
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}

config.keys = {
  {
    key = '%',
    mods = 'CTRL|SHIFT',
    action = act.SplitHorizontal { domain = 'CurrentPaneDomain' },
  },
}

return config
```

<ParamField path="domain" type="SpawnTabDomain">
  Domain to use for the new pane
</ParamField>

<ParamField path="args" type="string[]">
  Command to run in the new pane
</ParamField>

<ParamField path="cwd" type="string">
  Working directory for the new pane
</ParamField>

### SplitVertical

Split the current pane vertically (top and bottom):

```lua theme={null}
config.keys = {
  {
    key = '"',
    mods = 'CTRL|SHIFT',
    action = act.SplitVertical { domain = 'CurrentPaneDomain' },
  },
}
```

### SplitPane

Advanced pane splitting with more control:

```lua theme={null}
config.keys = {
  {
    key = 'd',
    mods = 'CTRL|SHIFT',
    action = act.SplitPane {
      direction = 'Right',
      size = { Percent = 30 },
      command = { args = { 'htop' } },
    },
  },
}
```

<ParamField path="direction" type="PaneDirection" required>
  Direction to split: `'Left'`, `'Right'`, `'Up'`, or `'Down'`
</ParamField>

<ParamField path="size" type="SplitSize">
  Size of the new pane:

  * `{ Percent = 50 }` - Percentage of available space (default: 50)
  * `{ Cells = 20 }` - Fixed number of cells (characters)
</ParamField>

<ParamField path="command" type="SpawnCommand">
  Command to run in the new pane
</ParamField>

<ParamField path="top_level" type="boolean" default="false">
  When `true`, split the entire tab instead of just the current pane
</ParamField>

## Navigating Panes

### ActivatePaneDirection

Move focus to an adjacent pane:

```lua theme={null}
config.keys = {
  {
    key = 'LeftArrow',
    mods = 'ALT',
    action = act.ActivatePaneDirection 'Left',
  },
  {
    key = 'RightArrow',
    mods = 'ALT',
    action = act.ActivatePaneDirection 'Right',
  },
  {
    key = 'UpArrow',
    mods = 'ALT',
    action = act.ActivatePaneDirection 'Up',
  },
  {
    key = 'DownArrow',
    mods = 'ALT',
    action = act.ActivatePaneDirection 'Down',
  },
}
```

<ParamField path="direction" type="string" required>
  Direction to move focus:

  * `'Left'`, `'Right'`, `'Up'`, `'Down'` - Navigate by direction
  * `'Next'` - Move to next pane in tree order
  * `'Prev'` - Move to previous pane in tree order
</ParamField>

<Note>
  When multiple panes are adjacent in the specified direction, WezTerm selects the most recently activated one
</Note>

### ActivatePaneByIndex

Activate a specific pane by its index:

```lua theme={null}
config.keys = {
  {
    key = '1',
    mods = 'ALT',
    action = act.ActivatePaneByIndex(0),
  },
}
```

<ParamField path="index" type="integer" required>
  Zero-based index of the pane to activate
</ParamField>

### PaneSelect

Display an interactive pane selector:

```lua theme={null}
config.keys = {
  {
    key = 'p',
    mods = 'CTRL|SHIFT',
    action = act.PaneSelect,
  },
  {
    key = 's',
    mods = 'CTRL|SHIFT',
    action = act.PaneSelect {
      mode = 'SwapWithActive',
      alphabet = 'asdfghjkl;',
    },
  },
}
```

<ParamField path="alphabet" type="string">
  Custom alphabet for pane labels. Defaults to `quick_select_alphabet` config
</ParamField>

<ParamField path="mode" type="PaneSelectMode">
  What to do with the selected pane:

  * `'Activate'` - Switch focus to the pane (default)
  * `'SwapWithActive'` - Swap positions with active pane
  * `'SwapWithActiveKeepFocus'` - Swap positions but keep focus on current pane
  * `'MoveToNewTab'` - Move pane to a new tab
  * `'MoveToNewWindow'` - Move pane to a new window
</ParamField>

<ParamField path="show_pane_ids" type="boolean" default="false">
  Show pane IDs in the selector
</ParamField>

## Resizing Panes

### AdjustPaneSize

Resize the active pane:

```lua theme={null}
config.keys = {
  {
    key = 'LeftArrow',
    mods = 'CTRL|SHIFT|ALT',
    action = act.AdjustPaneSize { 'Left', 5 },
  },
  {
    key = 'RightArrow',
    mods = 'CTRL|SHIFT|ALT',
    action = act.AdjustPaneSize { 'Right', 5 },
  },
  {
    key = 'UpArrow',
    mods = 'CTRL|SHIFT|ALT',
    action = act.AdjustPaneSize { 'Up', 5 },
  },
  {
    key = 'DownArrow',
    mods = 'CTRL|SHIFT|ALT',
    action = act.AdjustPaneSize { 'Down', 5 },
  },
}
```

<Note>
  This is commonly used with key tables to create a modal resize mode
</Note>

### Resize Mode with Key Tables

```lua theme={null}
config.leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 1000 }

config.keys = {
  {
    key = 'r',
    mods = 'LEADER',
    action = act.ActivateKeyTable {
      name = 'resize_pane',
      one_shot = false,
    },
  },
}

config.key_tables = {
  resize_pane = {
    { key = 'LeftArrow', action = act.AdjustPaneSize { 'Left', 1 } },
    { key = 'h', action = act.AdjustPaneSize { 'Left', 1 } },
    
    { key = 'RightArrow', action = act.AdjustPaneSize { 'Right', 1 } },
    { key = 'l', action = act.AdjustPaneSize { 'Right', 1 } },
    
    { key = 'UpArrow', action = act.AdjustPaneSize { 'Up', 1 } },
    { key = 'k', action = act.AdjustPaneSize { 'Up', 1 } },
    
    { key = 'DownArrow', action = act.AdjustPaneSize { 'Down', 1 } },
    { key = 'j', action = act.AdjustPaneSize { 'Down', 1 } },
    
    -- Cancel resize mode
    { key = 'Escape', action = 'PopKeyTable' },
  },
}
```

## Managing Panes

### CloseCurrentPane

Close the currently active pane:

```lua theme={null}
config.keys = {
  {
    key = 'w',
    mods = 'CTRL',
    action = act.CloseCurrentPane { confirm = true },
  },
}
```

<ParamField path="confirm" type="boolean" default="false">
  When `true`, shows a confirmation overlay before closing
</ParamField>

### TogglePaneZoomState

Zoom (maximize) the current pane, hiding others temporarily:

```lua theme={null}
config.keys = {
  {
    key = 'z',
    mods = 'CTRL|SHIFT',
    action = act.TogglePaneZoomState,
  },
}
```

<Tip>
  Press the same key binding again to unzoom and restore the pane layout
</Tip>

### SetPaneZoomState

Explicitly set the zoom state:

```lua theme={null}
config.keys = {
  { key = 'z', mods = 'ALT', action = act.SetPaneZoomState(true) },
  { key = 'u', mods = 'ALT', action = act.SetPaneZoomState(false) },
}
```

<ParamField path="zoomed" type="boolean" required>
  `true` to zoom the pane, `false` to unzoom
</ParamField>

### RotatePanes

Rotate pane positions:

```lua theme={null}
config.keys = {
  {
    key = 'r',
    mods = 'CTRL|SHIFT',
    action = act.RotatePanes 'Clockwise',
  },
  {
    key = 'r',
    mods = 'CTRL|SHIFT|ALT',
    action = act.RotatePanes 'CounterClockwise',
  },
}
```

<ParamField path="direction" type="string" required>
  * `'Clockwise'` - Rotate panes clockwise
  * `'CounterClockwise'` - Rotate panes counter-clockwise
</ParamField>

## Complete Example

<CodeGroup>
  ```lua Basic Pane Management theme={null}
  local wezterm = require 'wezterm'
  local act = wezterm.action
  local config = {}

  config.keys = {
    -- Split panes
    { key = '%', mods = 'CTRL|SHIFT', action = act.SplitHorizontal { domain = 'CurrentPaneDomain' } },
    { key = '"', mods = 'CTRL|SHIFT', action = act.SplitVertical { domain = 'CurrentPaneDomain' } },
    
    -- Navigate panes
    { key = 'LeftArrow', mods = 'ALT', action = act.ActivatePaneDirection 'Left' },
    { key = 'RightArrow', mods = 'ALT', action = act.ActivatePaneDirection 'Right' },
    { key = 'UpArrow', mods = 'ALT', action = act.ActivatePaneDirection 'Up' },
    { key = 'DownArrow', mods = 'ALT', action = act.ActivatePaneDirection 'Down' },
    
    -- Close pane
    { key = 'w', mods = 'CTRL', action = act.CloseCurrentPane { confirm = true } },
    
    -- Zoom pane
    { key = 'z', mods = 'CTRL|SHIFT', action = act.TogglePaneZoomState },
  }

  return config
  ```

  ```lua Advanced Pane Control theme={null}
  local wezterm = require 'wezterm'
  local act = wezterm.action
  local config = {}

  -- Leader key for pane operations
  config.leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 1000 }

  config.keys = {
    -- Split panes with leader
    { key = '|', mods = 'LEADER|SHIFT', action = act.SplitHorizontal { domain = 'CurrentPaneDomain' } },
    { key = '-', mods = 'LEADER', action = act.SplitVertical { domain = 'CurrentPaneDomain' } },
    
    -- Navigate panes (vim-style)
    { key = 'h', mods = 'LEADER', action = act.ActivatePaneDirection 'Left' },
    { key = 'l', mods = 'LEADER', action = act.ActivatePaneDirection 'Right' },
    { key = 'k', mods = 'LEADER', action = act.ActivatePaneDirection 'Up' },
    { key = 'j', mods = 'LEADER', action = act.ActivatePaneDirection 'Down' },
    
    -- Pane selector
    { key = 'p', mods = 'LEADER', action = act.PaneSelect },
    { key = 's', mods = 'LEADER', action = act.PaneSelect { mode = 'SwapWithActive' } },
    
    -- Zoom
    { key = 'z', mods = 'LEADER', action = act.TogglePaneZoomState },
    
    -- Rotate panes
    { key = 'r', mods = 'LEADER', action = act.RotatePanes 'Clockwise' },
    
    -- Enter resize mode
    {
      key = 'r',
      mods = 'LEADER|SHIFT',
      action = act.ActivateKeyTable {
        name = 'resize_pane',
        one_shot = false,
      },
    },
  }

  -- Resize mode key table
  config.key_tables = {
    resize_pane = {
      { key = 'LeftArrow', action = act.AdjustPaneSize { 'Left', 1 } },
      { key = 'h', action = act.AdjustPaneSize { 'Left', 1 } },
      
      { key = 'RightArrow', action = act.AdjustPaneSize { 'Right', 1 } },
      { key = 'l', action = act.AdjustPaneSize { 'Right', 1 } },
      
      { key = 'UpArrow', action = act.AdjustPaneSize { 'Up', 1 } },
      { key = 'k', action = act.AdjustPaneSize { 'Up', 1 } },
      
      { key = 'DownArrow', action = act.AdjustPaneSize { 'Down', 1 } },
      { key = 'j', action = act.AdjustPaneSize { 'Down', 1 } },
      
      { key = 'Escape', action = 'PopKeyTable' },
    },
  }

  return config
  ```

  ```lua Custom Pane Splits theme={null}
  local wezterm = require 'wezterm'
  local act = wezterm.action
  local config = {}

  config.keys = {
    -- Split with custom size
    {
      key = 'd',
      mods = 'CTRL|SHIFT',
      action = act.SplitPane {
        direction = 'Right',
        size = { Percent = 30 },
      },
    },
    
    -- Split with specific command
    {
      key = 'h',
      mods = 'CTRL|SHIFT',
      action = act.SplitPane {
        direction = 'Down',
        size = { Cells = 15 },
        command = { args = { 'htop' } },
      },
    },
    
    -- Top-level split (split entire tab)
    {
      key = 't',
      mods = 'CTRL|SHIFT|ALT',
      action = act.SplitPane {
        direction = 'Right',
        top_level = true,
      },
    },
  }

  return config
  ```
</CodeGroup>

## Related Actions

* [Tab Actions](/lua/keyassignment/tabs) - Manage tabs containing panes
* [Scrolling Actions](/lua/keyassignment/scrolling) - Scroll through pane output