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

# wezterm.action

> Key assignment action constructors for defining keyboard shortcuts and mouse bindings

The `wezterm.action` module provides constructors for defining key assignment actions in your configuration file. It offers an ergonomic way to express keyboard shortcuts, mouse bindings, and other input actions.

## Overview

`wezterm.action` is a special enum constructor type that makes it easier to define actions compared to the older table-based syntax. It provides:

* Type-safe action constructors
* Autocomplete-friendly syntax
* Clear error messages for typos
* Backward compatibility with older configs

## Constructor Syntax

Indexing `wezterm.action` with a valid KeyAssignment name acts as a constructor for that action type.

```lua theme={null}
wezterm.action.QuickSelectArgs  -- Constructor for QuickSelectArgs
wezterm.action.Copy             -- Constructor for Copy action
wezterm.action.ActivateTab      -- Constructor for ActivateTab
```

## Action Types

### Unit Variants (No Parameters)

Actions that don't require parameters can be referenced directly:

```lua theme={null}
local wezterm = require 'wezterm'

return {
  keys = {
    {
      key = 'c',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.Copy,
    },
    {
      key = 'v',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.Paste,
    },
  },
}
```

### Actions with Default Parameters

Some actions have optional parameters and can be used with or without arguments:

```lua theme={null}
local wezterm = require 'wezterm'

return {
  keys = {
    -- Use with defaults
    {
      key = ' ',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.QuickSelectArgs,
    },
    -- Or with custom parameters
    {
      key = 'y',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.QuickSelectArgs {
        alphabet = 'abc',
        patterns = { 'https?://\\S+' },
      },
    },
  },
}
```

### Tuple Variants (Positional Parameters)

Actions with positional parameters are called like functions:

```lua theme={null}
local wezterm = require 'wezterm'
local act = wezterm.action  -- Shortcut alias

return {
  keys = {
    { key = 'F1', mods = 'ALT', action = act.ActivatePaneByIndex(0) },
    { key = 'F2', mods = 'ALT', action = act.ActivatePaneByIndex(1) },
    { key = 'F3', mods = 'ALT', action = act.ActivatePaneByIndex(2) },
    
    { key = '{', mods = 'CTRL', action = act.ActivateTabRelative(-1) },
    { key = '}', mods = 'CTRL', action = act.ActivateTabRelative(1) },
  },
}
```

## Common Actions

### Tab Management

<CodeGroup>
  ```lua New Tab theme={null}
  {
    key = 't',
    mods = 'CTRL|SHIFT',
    action = wezterm.action.SpawnTab('CurrentPaneDomain'),
  }
  ```

  ```lua Close Tab theme={null}
  {
    key = 'w',
    mods = 'CTRL|SHIFT',
    action = wezterm.action.CloseCurrentTab { confirm = true },
  }
  ```

  ```lua Switch Tabs theme={null}
  {
    key = 'Tab',
    mods = 'CTRL',
    action = wezterm.action.ActivateTabRelative(1),
  }
  ```

  ```lua Activate Tab by Index theme={null}
  {
    key = '1',
    mods = 'ALT',
    action = wezterm.action.ActivateTab(0),  -- 0-indexed
  }
  ```
</CodeGroup>

### Pane Management

<CodeGroup>
  ```lua Split Horizontal theme={null}
  {
    key = '\"',
    mods = 'CTRL|SHIFT',
    action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' },
  }
  ```

  ```lua Split Vertical theme={null}
  {
    key = '%',
    mods = 'CTRL|SHIFT',
    action = wezterm.action.SplitVertical { domain = 'CurrentPaneDomain' },
  }
  ```

  ```lua Navigate Panes theme={null}
  {
    key = 'LeftArrow',
    mods = 'CTRL|SHIFT',
    action = wezterm.action.ActivatePaneDirection('Left'),
  }
  ```

  ```lua Close Pane theme={null}
  {
    key = 'w',
    mods = 'CTRL|SHIFT|ALT',
    action = wezterm.action.CloseCurrentPane { confirm = true },
  }
  ```
</CodeGroup>

### Font Size

<CodeGroup>
  ```lua Increase theme={null}
  {
    key = '+',
    mods = 'CTRL',
    action = wezterm.action.IncreaseFontSize,
  }
  ```

  ```lua Decrease theme={null}
  {
    key = '-',
    mods = 'CTRL',
    action = wezterm.action.DecreaseFontSize,
  }
  ```

  ```lua Reset theme={null}
  {
    key = '0',
    mods = 'CTRL',
    action = wezterm.action.ResetFontSize,
  }
  ```
</CodeGroup>

### Scrollback

<CodeGroup>
  ```lua Scroll by Page theme={null}
  {
    key = 'PageUp',
    mods = 'SHIFT',
    action = wezterm.action.ScrollByPage(-1),
  }
  ```

  ```lua Scroll by Line theme={null}
  {
    key = 'UpArrow',
    mods = 'SHIFT',
    action = wezterm.action.ScrollByLine(-1),
  }
  ```

  ```lua Scroll to Top/Bottom theme={null}
  {
    key = 'Home',
    mods = 'SHIFT',
    action = wezterm.action.ScrollToTop,
  }
  ```

  ```lua Clear Scrollback theme={null}
  {
    key = 'K',
    mods = 'CTRL|SHIFT',
    action = wezterm.action.ClearScrollback('ScrollbackAndViewport'),
  }
  ```
</CodeGroup>

### Copy and Paste

```lua theme={null}
local wezterm = require 'wezterm'

return {
  keys = {
    {
      key = 'c',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.CopyTo('Clipboard'),
    },
    {
      key = 'v',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.PasteFrom('Clipboard'),
    },
  },
}
```

### Search and Selection

```lua theme={null}
local wezterm = require 'wezterm'

return {
  keys = {
    {
      key = 'f',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.Search { CaseSensitiveString = '' },
    },
    {
      key = 'Space',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.QuickSelect,
    },
    {
      key = 'X',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.ActivateCopyMode,
    },
  },
}
```

### Multiple Actions

Execute multiple actions with a single key press:

```lua theme={null}
{
  key = 'E',
  mods = 'CTRL|SHIFT',
  action = wezterm.action.Multiple {
    wezterm.action.ClearScrollback('ScrollbackAndViewport'),
    wezterm.action.SendKey { key = 'L', mods = 'CTRL' },
  },
}
```

## Workspace Management

```lua theme={null}
local wezterm = require 'wezterm'

return {
  keys = {
    {
      key = 's',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.SwitchToWorkspace {
        name = 'default',
      },
    },
    {
      key = 'n',
      mods = 'CTRL|SHIFT',
      action = wezterm.action.SwitchToWorkspace {
        name = 'monitoring',
        spawn = {
          args = { 'htop' },
        },
      },
    },
  },
}
```

## Key Tables

Activate custom key tables for modal key bindings:

```lua theme={null}
{
  key = 'r',
  mods = 'LEADER',
  action = wezterm.action.ActivateKeyTable {
    name = 'resize_pane',
    one_shot = false,
    timeout_milliseconds = 1000,
  },
}
```

## Custom Events

Emit custom events that can be handled with event handlers:

```lua theme={null}
{
  key = 'u',
  mods = 'CTRL|SHIFT',
  action = wezterm.action.EmitEvent('trigger-my-event'),
}
```

## Checking Action Availability

You can check if an action exists before using it:

```lua theme={null}
local wezterm = require 'wezterm'

if wezterm.has_action('QuickSelectArgs') then
  wezterm.log_info('QuickSelectArgs is available')
end
```

## Older Syntax (Pre-20220624)

For backward compatibility, the older table syntax is still supported:

```lua theme={null}
local wezterm = require 'wezterm'

return {
  keys = {
    {
      key = '{',
      mods = 'CTRL',
      action = wezterm.action {
        ActivateTabRelative = -1,
      },
    },
  },
}
```

<Note>
  The new constructor syntax is recommended for all new configurations as it provides better type checking and clearer syntax.
</Note>

## Using Aliases

For brevity, create a shortcut alias:

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

return {
  keys = {
    { key = 't', mods = 'CTRL', action = act.SpawnTab('CurrentPaneDomain') },
    { key = 'w', mods = 'CTRL', action = act.CloseCurrentTab { confirm = false } },
  },
}
```

## Key Assignment Categories

Actions are available for:

* **Tabs**: Spawn, close, activate, move tabs
* **Panes**: Split, close, navigate, resize panes
* **Scrollback**: Scroll by page/line, search, clear
* **Copy/Paste**: Copy to clipboard, paste from clipboard
* **Font**: Increase, decrease, reset font size
* **Window**: Toggle fullscreen, hide, quit
* **Workspaces**: Switch, create workspaces
* **Launchers**: Show launcher, tab navigator
* **Custom**: Emit events, run callbacks

## Related Functions

* [wezterm.action\_callback()](/lua/wezterm/overview#actions) - Create custom action callbacks
* [wezterm.has\_action()](/lua/wezterm/overview#actions) - Check if action exists
* [wezterm.on()](/lua/wezterm/overview#state-management) - Register event handlers

## Source Reference

Implementation: `config/src/lua.rs:345`