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):

local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}

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

return config

domain · SpawnTabDomain

Domain to use for the new pane

args · string[]

Command to run in the new pane

cwd · string

Working directory for the new pane

SplitVertical

Split the current pane vertically (top and bottom):

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

SplitPane

Advanced pane splitting with more control:

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

direction · PaneDirection · required

Direction to split: 'Left', 'Right', 'Up', or 'Down'

size · SplitSize

Size of the new pane:

• { Percent = 50 } - Percentage of available space (default: 50)
• { Cells = 20 } - Fixed number of cells (characters)

command · SpawnCommand

Command to run in the new pane

top_level · boolean · default: "false"

When true, split the entire tab instead of just the current pane

Navigating Panes

ActivatePaneDirection

Move focus to an adjacent pane:

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',
  },
}

direction · 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

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

ActivatePaneByIndex

Activate a specific pane by its index:

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

index · integer · required

Zero-based index of the pane to activate

PaneSelect

Display an interactive pane selector:

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

alphabet · string

Custom alphabet for pane labels. Defaults to quick_select_alphabet config

mode · 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

show_pane_ids · boolean · default: "false"

Show pane IDs in the selector

Resizing Panes

AdjustPaneSize

Resize the active pane:

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

This is commonly used with key tables to create a modal resize mode

Resize Mode with Key Tables

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:

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

confirm · boolean · default: "false"

When true, shows a confirmation overlay before closing

TogglePaneZoomState

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

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

Press the same key binding again to unzoom and restore the pane layout

SetPaneZoomState

Explicitly set the zoom state:

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

zoomed · boolean · required

true to zoom the pane, false to unzoom

RotatePanes

Rotate pane positions:

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

direction · string · required

• 'Clockwise' - Rotate panes clockwise
• 'CounterClockwise' - Rotate panes counter-clockwise

Complete Example

Basic Pane Management

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

Related Actions

• Tab Actions - Manage tabs containing panes
• Scrolling Actions - Scroll through pane output