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

> Configure keyboard shortcuts and key assignments in WezTerm

## Overview

WezTerm allows you to customize keyboard shortcuts through the `keys` configuration option in your `.wezterm.lua` file. You can override default assignments, add new bindings, or disable existing ones.

## Basic Key Binding Configuration

Key bindings are defined in the `config.keys` table:

```lua theme={null}
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.keys = {
  {
    key = 't',
    mods = 'CTRL',
    action = wezterm.action.SpawnTab 'CurrentPaneDomain',
  },
  {
    key = 'w',
    mods = 'CTRL',
    action = wezterm.action.CloseCurrentTab { confirm = true },
  },
}

return config
```

## Modifier Keys

The following modifier keys are supported:

<ParamField path="SUPER | CMD | WIN" type="modifier">
  On macOS: `Command` key. On Windows: `Windows` key. On Linux: `Super` or `Hyper` key.
</ParamField>

<ParamField path="CTRL" type="modifier">
  The Control key. Left and right are equivalent.
</ParamField>

<ParamField path="SHIFT" type="modifier">
  The Shift key. Left and right are equivalent.
</ParamField>

<ParamField path="ALT | OPT | META" type="modifier">
  On macOS: `Option` key. On other systems: `Alt` or `Meta` key.
</ParamField>

<ParamField path="LEADER" type="modifier">
  A special modal modifier state. See [Leader Key](#leader-key) below.
</ParamField>

You can combine modifiers using the `|` symbol:

```lua theme={null}
config.keys = {
  { key = 'n', mods = 'CTRL|SHIFT', action = wezterm.action.SpawnWindow },
}
```

## Key Codes

The `key` value can be:

* **A single character**: `'a'`, `'1'`, `'='`, etc.
* **Special keys**: `Enter`, `Tab`, `Backspace`, `Delete`, `Escape`, `PageUp`, `PageDown`, `Home`, `End`
* **Arrow keys**: `LeftArrow`, `RightArrow`, `UpArrow`, `DownArrow`
* **Function keys**: `F1` through `F24`
* **Numpad keys**: `Numpad0` through `Numpad9`, `Multiply`, `Add`, `Subtract`, `Divide`
* **Media keys**: `VolumeUp`, `VolumeDown`, `VolumeMute`, `MediaPlayPause`, `MediaNextTrack`, `MediaPrevTrack`

## Physical vs Mapped Keys

WezTerm supports two ways to reference keys:

### Physical Keys

Physical keys reference the physical position on an ANSI US keyboard:

```lua theme={null}
config.keys = {
  { key = 'phys:A', mods = 'CTRL', action = wezterm.action.ActivateTab(0) },
}
```

### Mapped Keys

Mapped keys reference the character produced after keyboard layout mapping:

```lua theme={null}
config.keys = {
  { key = 'mapped:a', mods = 'CTRL', action = wezterm.action.ActivateTab(0) },
}
```

### Key Map Preference

Control the default behavior with `key_map_preference`:

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

## Disabling Default Bindings

You can disable default key bindings:

```lua theme={null}
config.keys = {
  -- Turn off CMD-m Hide action on macOS
  {
    key = 'm',
    mods = 'CMD',
    action = wezterm.action.DisableDefaultAssignment,
  },
}
```

## Leader Key

The leader key enables tmux-style key bindings with a prefix:

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

config.keys = {
  -- Leader + c creates a new tab
  {
    key = 'c',
    mods = 'LEADER',
    action = wezterm.action.SpawnTab 'CurrentPaneDomain',
  },
  -- Leader + | splits horizontally
  {
    key = '|',
    mods = 'LEADER|SHIFT',
    action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' },
  },
  -- Leader + - splits vertically
  {
    key = '-',
    mods = 'LEADER',
    action = wezterm.action.SplitVertical { domain = 'CurrentPaneDomain' },
  },
}
```

<Note>
  The leader key must be pressed within `timeout_milliseconds` before the next key.
</Note>

## Key Tables

Key tables enable modal key bindings:

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

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

config.key_tables = {
  resize_pane = {
    { key = 'LeftArrow', action = wezterm.action.AdjustPaneSize { 'Left', 1 } },
    { key = 'RightArrow', action = wezterm.action.AdjustPaneSize { 'Right', 1 } },
    { key = 'UpArrow', action = wezterm.action.AdjustPaneSize { 'Up', 1 } },
    { key = 'DownArrow', action = wezterm.action.AdjustPaneSize { 'Down', 1 } },
    { key = 'Escape', action = 'PopKeyTable' },
  },
}
```

## Common Key Binding Examples

### Tabs

```lua theme={null}
config.keys = {
  { key = 't', mods = 'CTRL', action = wezterm.action.SpawnTab 'CurrentPaneDomain' },
  { key = 'w', mods = 'CTRL', action = wezterm.action.CloseCurrentTab { confirm = true } },
  { key = 'Tab', mods = 'CTRL', action = wezterm.action.ActivateTabRelative(1) },
  { key = 'Tab', mods = 'CTRL|SHIFT', action = wezterm.action.ActivateTabRelative(-1) },
}
```

### Panes

```lua theme={null}
config.keys = {
  { key = '"', mods = 'CTRL|SHIFT', action = wezterm.action.SplitVertical { domain = 'CurrentPaneDomain' } },
  { key = '%', mods = 'CTRL|SHIFT', action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' } },
  { key = 'h', mods = 'CTRL|SHIFT', action = wezterm.action.ActivatePaneDirection 'Left' },
  { key = 'l', mods = 'CTRL|SHIFT', action = wezterm.action.ActivatePaneDirection 'Right' },
}
```

### Font Size

```lua theme={null}
config.keys = {
  { key = '+', mods = 'CTRL', action = wezterm.action.IncreaseFontSize },
  { key = '-', mods = 'CTRL', action = wezterm.action.DecreaseFontSize },
  { key = '0', mods = 'CTRL', action = wezterm.action.ResetFontSize },
}
```

## See Also

* [Key Assignment Actions](/lua/keyassignment/overview)
* [Mouse Bindings](/config/mouse)
* [Default Key Bindings](https://wezfurlong.org/wezterm/config/default-keys.html)