Mouse Bindings

Configure mouse button actions and gestures in WezTerm

Overview

WezTerm supports customizable mouse bindings through the mouse_bindings configuration option. You can bind actions to mouse clicks, double-clicks, triple-clicks, and drag operations with modifier keys.

Basic Mouse Binding Configuration

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.mouse_bindings = {
  {
    event = { Up = { streak = 1, button = 'Left' } },
    mods = 'CTRL',
    action = wezterm.action.OpenLinkAtMouseCursor,
  },
}

return config

Mouse Events

Mouse events consist of:

event · object · required

The mouse event to bind.

mods · string

Optional modifier keys (CTRL, SHIFT, ALT, SUPER).

action · KeyAssignment · required

The action to perform.

Event Types

Down - Mouse button pressed:

event = { Down = { streak = 1, button = 'Left' } }

Up - Mouse button released:

event = { Up = { streak = 1, button = 'Left' } }

Drag - Mouse moved while button held:

event = { Drag = { streak = 1, button = 'Left' } }

Streak Values

• streak = 1 - Single click
• streak = 2 - Double click
• streak = 3 - Triple click

Mouse Buttons

• 'Left' - Left mouse button
• 'Right' - Right mouse button
• 'Middle' - Middle mouse button (wheel click)
• 'WheelUp' - Scroll wheel up
• 'WheelDown' - Scroll wheel down

Common Mouse Binding Examples

Open Links with Ctrl+Click

config.mouse_bindings = {
  {
    event = { Up = { streak = 1, button = 'Left' } },
    mods = 'CTRL',
    action = wezterm.action.OpenLinkAtMouseCursor,
  },
}

Select Word on Double Click

config.mouse_bindings = {
  {
    event = { Down = { streak = 2, button = 'Left' } },
    mods = 'NONE',
    action = wezterm.action.SelectTextAtMouseCursor 'Word',
  },
}

Select Line on Triple Click

config.mouse_bindings = {
  {
    event = { Down = { streak = 3, button = 'Left' } },
    mods = 'NONE',
    action = wezterm.action.SelectTextAtMouseCursor 'Line',
  },
}

Paste on Middle Click

config.mouse_bindings = {
  {
    event = { Up = { streak = 1, button = 'Middle' } },
    mods = 'NONE',
    action = wezterm.action.PasteFrom 'PrimarySelection',
  },
}

Custom Scrolling

config.mouse_bindings = {
  {
    event = { Down = { streak = 1, button = 'WheelUp' } },
    mods = 'CTRL',
    action = wezterm.action.IncreaseFontSize,
  },
  {
    event = { Down = { streak = 1, button = 'WheelDown' } },
    mods = 'CTRL',
    action = wezterm.action.DecreaseFontSize,
  },
}

Mouse Reporting

WezTerm supports SGR mouse reporting for applications like vim and tmux. This is enabled by default.

Disable Mouse Reporting for Specific Programs

config.bypass_mouse_reporting_modifiers = 'SHIFT'

Holding SHIFT will bypass mouse reporting and allow terminal-level mouse actions.

Disabling Default Mouse Bindings

To disable a default mouse binding:

config.mouse_bindings = {
  {
    event = { Up = { streak = 1, button = 'Left' } },
    mods = 'NONE',
    action = wezterm.action.DisableDefaultAssignment,
  },
}

Advanced Examples

Context Menu on Right Click

config.mouse_bindings = {
  {
    event = { Down = { streak = 1, button = 'Right' } },
    mods = 'NONE',
    action = wezterm.action_callback(function(window, pane)
      local clipboard = window:get_clipboard()
      window:toast_notification('WezTerm', clipboard, nil, 3000)
    end),
  },
}

Select with Alt+Click

config.mouse_bindings = {
  {
    event = { Down = { streak = 1, button = 'Left' } },
    mods = 'ALT',
    action = wezterm.action.SelectTextAtMouseCursor 'Cell',
  },
}

Drag to Create New Window

config.mouse_bindings = {
  {
    event = { Drag = { streak = 1, button = 'Left' } },
    mods = 'CTRL',
    action = wezterm.action.StartWindowDrag,
  },
}

Mouse Cursor Themes

Configure the mouse cursor appearance:

-- On X11/Wayland
config.xcursor_theme = 'Adwaita'
config.xcursor_size = 24

See Also

• Key Bindings
• Mouse Actions
• Selection Actions