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.

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:

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:

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:

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

New Tab

{
  key = 't',
  mods = 'CTRL|SHIFT',
  action = wezterm.action.SpawnTab('CurrentPaneDomain'),
}

Pane Management

Split Horizontal

{
  key = '\"',
  mods = 'CTRL|SHIFT',
  action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' },
}

Font Size

Increase

{
  key = '+',
  mods = 'CTRL',
  action = wezterm.action.IncreaseFontSize,
}

Scrollback

Scroll by Page

{
  key = 'PageUp',
  mods = 'SHIFT',
  action = wezterm.action.ScrollByPage(-1),
}

Copy and Paste

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

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:

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

Workspace Management

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:

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

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

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:

local wezterm = require 'wezterm'

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

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

Using Aliases

For brevity, create a shortcut alias:

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() - Create custom action callbacks
• wezterm.has_action() - Check if action exists
• wezterm.on() - Register event handlers

Source Reference

Implementation: config/src/lua.rs:345