Key Binding Configuration

Configure keyboard shortcuts and key bindings in WezTerm using Lua

Key Binding Configuration

WezTerm provides a powerful and flexible key binding system that allows you to customize keyboard shortcuts, create modal key tables, and configure leader keys.

Basic Key Bindings

Defining Key Bindings

Key bindings are configured using the keys configuration option:

local wezterm = require 'wezterm'
local config = wezterm.config_builder()
local act = wezterm.action

config.keys = {
  -- Create a new tab in the same domain
  {
    key = 't',
    mods = 'CTRL|SHIFT',
    action = act.SpawnTab 'CurrentPaneDomain',
  },
  -- Close the current tab
  {
    key = 'w',
    mods = 'CTRL|SHIFT',
    action = act.CloseCurrentTab { confirm = true },
  },
}

return config

keys · array · default: "[]"

An array of key binding definitions. Each binding specifies a key, modifiers, and an action.

Key Binding Structure

Each key binding is a table with these fields:

key · string · required

The key to bind. Can be a character (‘a’), named key (‘Enter’, ‘Tab’, ‘F1’), or keycode.

mods · string · default: "''"

Modifier keys, combined with |. Valid values: SHIFT, CTRL, ALT, SUPER, CMD, WIN, META

action · KeyAssignment · required

The action to perform when the key combination is pressed.

Modifier Keys

Single Modifier

config.keys = {
  { key = 'c', mods = 'CTRL', action = act.CopyTo 'Clipboard' },
}

• SUPER maps to CMD on macOS and WIN on Windows/Linux
• CMD and WIN are aliases and can be used interchangeably
• Modifiers are case-insensitive

Common Key Actions

Tab Management

config.keys = {
  -- Create new tab
  { key = 't', mods = 'CTRL|SHIFT', action = act.SpawnTab 'CurrentPaneDomain' },
  
  -- Close current tab
  { key = 'w', mods = 'CTRL|SHIFT', action = act.CloseCurrentTab { confirm = true } },
  
  -- Switch to next tab
  { key = 'Tab', mods = 'CTRL', action = act.ActivateTabRelative(1) },
  
  -- Switch to previous tab
  { key = 'Tab', mods = 'CTRL|SHIFT', action = act.ActivateTabRelative(-1) },
  
  -- Switch to specific tab
  { key = '1', mods = 'ALT', action = act.ActivateTab(0) },
  { key = '2', mods = 'ALT', action = act.ActivateTab(1) },
  { key = '3', mods = 'ALT', action = act.ActivateTab(2) },
}

Pane Management

config.keys = {
  -- Split horizontally
  {
    key = '|',
    mods = 'CTRL|SHIFT',
    action = act.SplitHorizontal { domain = 'CurrentPaneDomain' },
  },
  
  -- Split vertically
  {
    key = '_',
    mods = 'CTRL|SHIFT',
    action = act.SplitVertical { domain = 'CurrentPaneDomain' },
  },
  
  -- Close current pane
  {
    key = 'x',
    mods = 'CTRL|SHIFT',
    action = act.CloseCurrentPane { confirm = true },
  },
  
  -- Navigate panes
  { key = 'h', mods = 'CTRL|SHIFT', action = act.ActivatePaneDirection 'Left' },
  { key = 'l', mods = 'CTRL|SHIFT', action = act.ActivatePaneDirection 'Right' },
  { key = 'k', mods = 'CTRL|SHIFT', action = act.ActivatePaneDirection 'Up' },
  { key = 'j', mods = 'CTRL|SHIFT', action = act.ActivatePaneDirection 'Down' },
}

Copy and Paste

config.keys = {
  -- Copy to clipboard
  { key = 'c', mods = 'CTRL|SHIFT', action = act.CopyTo 'Clipboard' },
  
  -- Paste from clipboard
  { key = 'v', mods = 'CTRL|SHIFT', action = act.PasteFrom 'Clipboard' },
  
  -- Copy to primary selection (X11)
  { key = 'c', mods = 'CTRL', action = act.CopyTo 'PrimarySelection' },
  
  -- Paste from primary selection (X11)
  { key = 'v', mods = 'CTRL', action = act.PasteFrom 'PrimarySelection' },
}

Font Size

config.keys = {
  -- Increase font size
  { key = '+', mods = 'CTRL', action = act.IncreaseFontSize },
  { key = '=', mods = 'CTRL', action = act.IncreaseFontSize },
  
  -- Decrease font size
  { key = '-', mods = 'CTRL', action = act.DecreaseFontSize },
  
  -- Reset font size
  { key = '0', mods = 'CTRL', action = act.ResetFontSize },
}

Scrollback

config.keys = {
  -- Scroll up one page
  { key = 'PageUp', mods = 'SHIFT', action = act.ScrollByPage(-1) },
  
  -- Scroll down one page
  { key = 'PageDown', mods = 'SHIFT', action = act.ScrollByPage(1) },
  
  -- Scroll to top
  { key = 'Home', mods = 'SHIFT', action = act.ScrollToTop },
  
  -- Scroll to bottom
  { key = 'End', mods = 'SHIFT', action = act.ScrollToBottom },
}

Disabling Default Key Bindings

To start with a clean slate and define only your own key bindings:

disable_default_key_bindings · boolean · default: "false"

When true, WezTerm’s default key bindings are disabled.

config.disable_default_key_bindings = true

-- Then define only the keys you want
config.keys = {
  { key = 'c', mods = 'CTRL|SHIFT', action = act.CopyTo 'Clipboard' },
  { key = 'v', mods = 'CTRL|SHIFT', action = act.PasteFrom 'Clipboard' },
}

Leader Key

A leader key works like in tmux - you press the leader key combination, then press another key within a timeout:

leader · table · default: "nil"

Configuration for the leader key. Includes the key, modifiers, and timeout.

config.leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 1000 }

config.keys = {
  -- Send CTRL-A when pressing CTRL-A twice
  {
    key = 'a',
    mods = 'LEADER|CTRL',
    action = act.SendKey { key = 'a', mods = 'CTRL' },
  },
  
  -- Split horizontal with leader + |
  {
    key = '|',
    mods = 'LEADER|SHIFT',
    action = act.SplitHorizontal { domain = 'CurrentPaneDomain' },
  },
  
  -- Split vertical with leader + -
  {
    key = '-',
    mods = 'LEADER',
    action = act.SplitVertical { domain = 'CurrentPaneDomain' },
  },
}

When a key binding uses the LEADER modifier, it requires pressing the leader key first.

Key Tables

Key tables allow you to create modal key binding sets, similar to vim modes:

key_tables · table · default: "{}"

A table mapping key table names to arrays of key bindings.

config.leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 1000 }

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

config.key_tables = {
  resize_pane = {
    { key = 'h', action = act.AdjustPaneSize { 'Left', 5 } },
    { key = 'l', action = act.AdjustPaneSize { 'Right', 5 } },
    { key = 'k', action = act.AdjustPaneSize { 'Up', 5 } },
    { key = 'j', action = act.AdjustPaneSize { 'Down', 5 } },
    
    -- Cancel the mode
    { key = 'Escape', action = 'PopKeyTable' },
    { key = 'Enter', action = 'PopKeyTable' },
  },
}

Key Table Options

When activating a key table:

name · string · required

The name of the key table to activate.

one_shot · boolean · default: "true"

When true, the key table is automatically deactivated after one key press.

timeout_milliseconds · number · default: "nil"

Optional timeout after which the key table is automatically deactivated.

replace_current · boolean · default: "false"

When true, replaces the current key table instead of stacking.

Physical vs Mapped Keys

key_map_preference · string · default: "'Mapped'"

Controls whether keys are matched by physical position or mapped character. Valid values: Physical, Mapped

config.key_map_preference = 'Physical'

You can also specify keys using explicit physical or mapped notation:

config.keys = {
  -- Match by physical key position (ANSI US layout)
  { key = 'phys:A', mods = 'CTRL', action = act.SendString 'Hello' },
  
  -- Match by mapped character
  { key = 'mapped:a', mods = 'CTRL', action = act.SendString 'World' },
  
  -- Match by raw scan code
  { key = 'raw:123', mods = 'CTRL', action = act.SendString 'Raw' },
}

Mouse Bindings

You can also bind mouse events to actions:

mouse_bindings · array · default: "[]"

An array of mouse binding definitions.

config.mouse_bindings = {
  -- Right click to paste
  {
    event = { Down = { streak = 1, button = 'Right' } },
    mods = 'NONE',
    action = act.PasteFrom 'Clipboard',
  },
  
  -- CTRL-click to open hyperlink
  {
    event = { Up = { streak = 1, button = 'Left' } },
    mods = 'CTRL',
    action = act.OpenLinkAtMouseCursor,
  },
  
  -- Middle click to paste primary selection
  {
    event = { Down = { streak = 1, button = 'Middle' } },
    mods = 'NONE',
    action = act.PasteFrom 'PrimarySelection',
  },
}

Disable Default Mouse Bindings

disable_default_mouse_bindings · boolean · default: "false"

When true, WezTerm’s default mouse bindings are disabled.

config.disable_default_mouse_bindings = true

Debug Key Events

debug_key_events · boolean · default: "false"

When true, logs all key events to help debug key binding issues.

config.debug_key_events = true

This will show detailed information about key presses in the debug overlay (CTRL+SHIFT+L).

Complete Key Configuration Example

local wezterm = require 'wezterm'
local config = wezterm.config_builder()
local act = wezterm.action

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

-- Key bindings
config.keys = {
  -- Tabs
  { key = 't', mods = 'CTRL|SHIFT', action = act.SpawnTab 'CurrentPaneDomain' },
  { key = 'w', mods = 'CTRL|SHIFT', action = act.CloseCurrentTab { confirm = true } },
  { key = 'Tab', mods = 'CTRL', action = act.ActivateTabRelative(1) },
  { key = 'Tab', mods = 'CTRL|SHIFT', action = act.ActivateTabRelative(-1) },
  
  -- Panes
  {
    key = '|',
    mods = 'LEADER|SHIFT',
    action = act.SplitHorizontal { domain = 'CurrentPaneDomain' },
  },
  {
    key = '-',
    mods = 'LEADER',
    action = act.SplitVertical { domain = 'CurrentPaneDomain' },
  },
  { 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' },
  
  -- Resize mode
  {
    key = 'r',
    mods = 'LEADER',
    action = act.ActivateKeyTable {
      name = 'resize_pane',
      one_shot = false,
    },
  },
  
  -- Copy and Paste
  { key = 'c', mods = 'CTRL|SHIFT', action = act.CopyTo 'Clipboard' },
  { key = 'v', mods = 'CTRL|SHIFT', action = act.PasteFrom 'Clipboard' },
  
  -- Font size
  { key = '+', mods = 'CTRL', action = act.IncreaseFontSize },
  { key = '-', mods = 'CTRL', action = act.DecreaseFontSize },
  { key = '0', mods = 'CTRL', action = act.ResetFontSize },
}

-- Key tables
config.key_tables = {
  resize_pane = {
    { key = 'h', action = act.AdjustPaneSize { 'Left', 5 } },
    { key = 'l', action = act.AdjustPaneSize { 'Right', 5 } },
    { key = 'k', action = act.AdjustPaneSize { 'Up', 5 } },
    { key = 'j', action = act.AdjustPaneSize { 'Down', 5 } },
    { key = 'Escape', action = 'PopKeyTable' },
  },
}

return config

See Also

• Default Key Bindings - Complete list of default bindings
• Key Assignments Overview - All available actions
• Configuration Files - Configuration basics