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

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

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

<ParamField path="keys" type="array" default="[]">
  An array of key binding definitions. Each binding specifies a key, modifiers, and an action.
</ParamField>

### Key Binding Structure

Each key binding is a table with these fields:

<ParamField path="key" type="string" required>
  The key to bind. Can be a character ('a'), named key ('Enter', 'Tab', 'F1'), or keycode.
</ParamField>

<ParamField path="mods" type="string" default="''">
  Modifier keys, combined with `|`. Valid values: `SHIFT`, `CTRL`, `ALT`, `SUPER`, `CMD`, `WIN`, `META`
</ParamField>

<ParamField path="action" type="KeyAssignment" required>
  The action to perform when the key combination is pressed.
</ParamField>

### Modifier Keys

<CodeGroup>
  ```lua Single Modifier theme={null}
  config.keys = {
    { key = 'c', mods = 'CTRL', action = act.CopyTo 'Clipboard' },
  }
  ```

  ```lua Multiple Modifiers theme={null}
  config.keys = {
    { key = 'v', mods = 'CTRL|SHIFT', action = act.PasteFrom 'Clipboard' },
  }
  ```

  ```lua Platform-Specific theme={null}
  config.keys = {
    -- CMD on macOS, CTRL on others
    { key = 't', mods = 'SUPER', action = act.SpawnTab 'CurrentPaneDomain' },
  }
  ```
</CodeGroup>

<Note>
  * `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
</Note>

## Common Key Actions

### Tab Management

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

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

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

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

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

<ParamField path="disable_default_key_bindings" type="boolean" default="false">
  When true, WezTerm's default key bindings are disabled.
</ParamField>

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

<ParamField path="leader" type="table" default="nil">
  Configuration for the leader key. Includes the key, modifiers, and timeout.
</ParamField>

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

<Note>
  When a key binding uses the `LEADER` modifier, it requires pressing the leader key first.
</Note>

## Key Tables

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

<ParamField path="key_tables" type="table" default="{}">
  A table mapping key table names to arrays of key bindings.
</ParamField>

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

<ParamField path="name" type="string" required>
  The name of the key table to activate.
</ParamField>

<ParamField path="one_shot" type="boolean" default="true">
  When true, the key table is automatically deactivated after one key press.
</ParamField>

<ParamField path="timeout_milliseconds" type="number" default="nil">
  Optional timeout after which the key table is automatically deactivated.
</ParamField>

<ParamField path="replace_current" type="boolean" default="false">
  When true, replaces the current key table instead of stacking.
</ParamField>

## Physical vs Mapped Keys

<ParamField path="key_map_preference" type="string" default="'Mapped'">
  Controls whether keys are matched by physical position or mapped character. Valid values: `Physical`, `Mapped`
</ParamField>

```lua theme={null}
config.key_map_preference = 'Physical'
```

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

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

<ParamField path="mouse_bindings" type="array" default="[]">
  An array of mouse binding definitions.
</ParamField>

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

<ParamField path="disable_default_mouse_bindings" type="boolean" default="false">
  When true, WezTerm's default mouse bindings are disabled.
</ParamField>

```lua theme={null}
config.disable_default_mouse_bindings = true
```

## Debug Key Events

<ParamField path="debug_key_events" type="boolean" default="false">
  When true, logs all key events to help debug key binding issues.
</ParamField>

```lua theme={null}
config.debug_key_events = true
```

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

## Complete Key Configuration Example

```lua theme={null}
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](https://wezfurlong.org/wezterm/config/default-keys.html) - Complete list of default bindings
* [Key Assignments Overview](/lua/keyassignment/overview) - All available actions
* [Configuration Files](/config/files) - Configuration basics