> ## 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 Assignment Overview

> Learn how to bind keys to actions in WezTerm using Lua configuration

## Introduction

Key assignments in WezTerm allow you to bind keyboard shortcuts to specific actions. The key assignment system is highly flexible, supporting modifiers, key tables, and complex action sequences.

## Basic Key Binding

Key bindings are configured through the `keys` table in your configuration file:

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

config.keys = {
  {
    key = 't',
    mods = 'CTRL|SHIFT',
    action = act.SpawnTab 'CurrentPaneDomain',
  },
}

return config
```

## Key Assignment Structure

Each key binding consists of three components:

<ParamField path="key" type="string" required>
  The key to bind. Can be a letter, number, function key (F1-F24), or special key name
</ParamField>

<ParamField path="mods" type="string">
  Modifier keys to require. Common modifiers include:

  * `CTRL` - Control key
  * `SHIFT` - Shift key
  * `ALT` - Alt/Option key
  * `SUPER` or `CMD` - Windows/Command key

  Combine multiple modifiers with `|`, e.g., `CTRL|SHIFT`
</ParamField>

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

## Key Assignment Categories

Key assignments are organized into several categories:

### Tab Management

Actions for creating, closing, and navigating between tabs:

* `SpawnTab` - Create new tabs
* `ActivateTab` - Switch to specific tabs
* `CloseCurrentTab` - Close tabs
* `MoveTab` - Reorder tabs

[Learn more about tab actions →](/lua/keyassignment/tabs)

### Pane Management

Actions for splitting, resizing, and navigating panes:

* `SplitHorizontal` / `SplitVertical` - Split panes
* `ActivatePaneDirection` - Navigate between panes
* `AdjustPaneSize` - Resize panes
* `CloseCurrentPane` - Close panes

[Learn more about pane actions →](/lua/keyassignment/panes)

### Copy and Paste

Actions for clipboard operations:

* `CopyTo` - Copy selection to clipboard
* `PasteFrom` - Paste from clipboard
* `SelectTextAtMouseCursor` - Start text selection

[Learn more about copy/paste actions →](/lua/keyassignment/copy-paste)

### Scrolling

Actions for scrolling through terminal output:

* `ScrollByPage` - Scroll by pages
* `ScrollByLine` - Scroll by lines
* `ScrollToTop` / `ScrollToBottom` - Jump to extremes
* `ScrollToPrompt` - Navigate by shell prompts

[Learn more about scrolling actions →](/lua/keyassignment/scrolling)

### Search

Actions for searching terminal content:

* `Search` - Open search overlay
* `ActivateCopyMode` - Enter copy mode for keyboard navigation

[Learn more about search actions →](/lua/keyassignment/search)

## Multiple Actions

You can bind a single key combination to multiple actions using the `Multiple` action:

```lua theme={null}
config.keys = {
  {
    key = 'E',
    mods = 'CTRL|SHIFT',
    action = act.Multiple {
      act.CopyTo 'Clipboard',
      act.ClearSelection,
    },
  },
}
```

## Disabling Default Bindings

To disable a default key binding without assigning a new action:

```lua theme={null}
config.keys = {
  {
    key = 'Enter',
    mods = 'ALT',
    action = act.DisableDefaultAssignment,
  },
}
```

## Key Tables

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

```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 = 'RightArrow', action = act.AdjustPaneSize { 'Right', 1 } },
    { key = 'UpArrow', action = act.AdjustPaneSize { 'Up', 1 } },
    { key = 'DownArrow', action = act.AdjustPaneSize { 'Down', 1 } },
    { key = 'Escape', action = 'PopKeyTable' },
  },
}
```

## Special Keys

WezTerm supports a wide range of special keys:

* Function keys: `F1` through `F24`
* Navigation: `UpArrow`, `DownArrow`, `LeftArrow`, `RightArrow`, `PageUp`, `PageDown`, `Home`, `End`
* Editing: `Insert`, `Delete`, `Backspace`, `Enter`, `Tab`, `Escape`
* Media keys: `VolumeUp`, `VolumeDown`, `VolumeMute`, `Play`, `Pause`

## Best Practices

<Tip>
  Use the `act` alias for `wezterm.action` to make your configuration more concise and readable
</Tip>

<Warning>
  Be careful when overriding default key bindings. Some applications rely on specific key combinations being passed through to the terminal
</Warning>

<Note>
  You can view all active key bindings by pressing `CTRL+SHIFT+L` (or your configured key) to open the command palette, then selecting "Show Launcher" → "Key Assignments"
</Note>